Professional Wordpress® Design and Development

ffirs.indd i 04/12/12 5:12 PM PROFESSIONAL WORDPRESS®: DESIGN AND DEVELOPMENT, SECOND EDITION

INTRODUCTION ...... xxi

CHAPTER 1 First Post ...... 1 CHAPTER 2 Code Overview...... 21 CHAPTER 3 Working with WordPress Locally ...... 41 CHAPTER 4 Tour of the Core ...... 57 CHAPTER 5 The Loop ...... 73 CHAPTER 6 Data Management ...... 101 CHAPTER 7 Custom Post Types, Custom Taxonomies, and Metadata ...... 115 CHAPTER 8 Plugin Development ...... 139 CHAPTER 9 Theme Development ...... 211 CHAPTER 10 Multisite ...... 259 CHAPTER 11 Content Aggregation ...... 289 CHAPTER 12 Crafting a User Experience ...... 309 CHAPTER 13 Statistics, Scalability, Security, and Spam ...... 337 CHAPTER 14 WordPress as a Content Management System ...... 365 CHAPTER 15 WordPress in the Enterprise ...... 383 CHAPTER 16 WordPress Developer Community ...... 397

INDEX ...... 411

ffirs.indd i 04/12/12 5:12 PM ffirs.indd ii 04/12/12 5:12 PM PROFESSIONAL WordPress ®

ffirs.indd iii 04/12/12 5:12 PM ffirs.indd iv 04/12/12 5:12 PM PROFESSIONAL WordPress ® DESIGN AND DEVELOPMENT Second Edition

Brad Williams David Damstra Hal Stern

John Wiley & Sons, Inc.

ffirs.indd v 04/12/12 5:12 PM Professional WordPress®: Design and Development, Second Edition Published by John Wiley & Sons, Inc. 10475 Crosspoint Boulevard Indianapolis, IN 46256 www.wiley.com Copyright © 2013 by John Wiley & Sons, Inc., Indianapolis, Indiana Published simultaneously in Canada ISBN: 978-1-118-44227-2 ISBN: 978--1118-44229-6 (ebk) ISBN: 978-1-118-60438-0 (ebk) ISBN: 978-1-118-60423-6 (ebk) Manufactured in the United States of America 10 9 8 7 6 5 4 3 2 1 No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, scanning or otherwise, except as permitted under Sections 107 or 108 of the 1976 United States Copyright Act, without either the prior written permission of the Publisher, or authorization through payment of the appropriate per-copy fee to the Copyright Clearance Center, 222 Rosewood Drive, Danvers, MA 01923, (978) 750-8400, fax (978) 646-8600. Requests to the Publisher for permission should be addressed to the Permissions Department, John Wiley & Sons, Inc., 111 River Street, Hoboken, NJ 07030, (201) 748-6011, fax (201) 748-6008, or online at http://www.wiley.com/go/permissions. Limit of Liability/Disclaimer of Warranty: The publisher and the author make no representations or warranties with respect to the accuracy or completeness of the contents of this work and specifi cally disclaim all warranties, including without limitation warranties of fi tness for a particular purpose. No warranty may be created or extended by sales or promotional materials. The advice and strategies contained herein may not be suitable for every situation. This work is sold with the understanding that the publisher is not engaged in rendering legal, accounting, or other professional services. If professional assistance is required, the services of a competent professional person should be sought. Neither the publisher nor the author shall be liable for damages arising herefrom. The fact that an organization or Web site is referred to in this work as a citation and/or a potential source of further information does not mean that the author or the publisher endorses the information the organization or Web site may provide or recommendations it may make. Further, readers should be aware that Internet Web sites listed in this work may have changed or disappeared between when this work was written and when it is read. For general information on our other products and services please contact our Customer Care Department within the United States at (877) 762-2974, outside the United States at (317) 572-3993 or fax (317) 572-4002. Wiley publishes in a variety of print and electronic formats and by print-on-demand. Some material included with standard print versions of this book may not be included in e-books or in print-on-demand. If this book refers to media such as a CD or DVD that is not included in the version you purchased, you may download this material at http://booksupport.wiley.com. For more information about Wiley products, visit www.wiley.com. Library of Congress Control Number: 2012950504 Trademarks: Wiley, the Wiley logo, Wrox, the Wrox logo, Wrox Programmer to Programmer, and related trade dress are trademarks or registered trademarks of John Wiley & Sons, Inc. and/or its affi liates, in the United States and other countries, and may not be used without written permission. WordPress is a registered trademark of WordPress Foundation. All other trademarks are the property of their respective owners. John Wiley & Sons, Inc., is not associated with any product or vendor mentioned in this book.

ffirs.indd vi 04/12/12 5:12 PM For my wife, my partner, my best friend April Williams. You’ll never know how much you mean to me. Thank you for putting up with my nerdy ways and always supporting me.

—Brad Williams

For my loving wife Holly, my children - Jack, Justin and Jonah. Thanks for your love and support.

—David Damstra

For Toby, whose patience grows with each project.

—Hal Stern

ffirs.indd vii 04/12/12 5:12 PM CREDITS

EXECUTIVE EDITOR PRODUCTION MANAGER Carol Long Tim Tate

PROJECT EDITOR VICE PRESIDENT AND EXECUTIVE GROUP Christina Haviland PUBLISHER Richard Swadley TECHNICAL EDITOR Hal Stern VICE PRESIDENT AND EXECUTIVE PUBLISHER Neil Edde PRODUCTION EDITOR Daniel Scribner ASSOCIATE PUBLISHER Jim Minatel COPY EDITOR Nancy Rapoport PROJECT COORDINATOR, COVER Katie Crocker EDITORIAL MANAGER Mary Beth Wakeﬁ eld PROOFREADER Sarah Kaikini, Word One FREELANCER EDITORIAL MANAGER Rosemarie Graham INDEXER Robert Swanson ASSOCIATE DIRECTOR OF MARKETING David Mayhew COVER DESIGNER Elizabeth Brooks MARKETING MANAGER Ashley Zurcher COVER IMAGE © Karen Phillips / iStockphoto BUSINESS MANAGER Amy Knies

ffirs.indd viii 04/12/12 5:12 PM ABOUT THE AUTHORS

BRAD WILLIAMS is the co-founder of WebDevStudios.com, a cohost on the WP Late Night podcast, and the coauthor of Professional WordPress and Professional WordPress Plugin Development. Brad has been developing websites for over 15 years, including the last 5 where he has focused on open-source technologies like WordPress. Brad has given presentations at various WordCamps across the country and is a co-organizer of the Philadelphia WordPress Meetup and WordCamp Philly. You can follow Brad online on his personal blog at http://strangework.com and on Twitter @williamsba.

DAVID DAMSTRA is a vice president of Professional Services for CU*Answers, a credit union service organization. David manages a team of developers to create websites and web applications for the fi nancial industry. David’s team uses WordPress as the foundation for many web projects. David is also a Zend Certifi ed Engineer for PHP5. You can fi nd David online professionally at http:// ws.cuanswers.com where he focuses on web technology and best practices for web development, especially pertaining to the credit union industry, and personally at http://mirmillo.com where he talks about his family and home brewing.

HAL STERN is a Vice President with a major technology company focusing on software architecture for programmable networks and architectures for “big data” applications. Hal began blogging as part of a corporate communications effort at Sun Microsystems, and has been using WordPress to share thoughts on music, sports, food, and New Jersey for the past fi ve years. Hal’s affi nity for WordPress internals began when he was trying to determine how a mangled URL returned almost- correct content, and that curiosity has turned into his contributions to this book and a WordCamp talk. Hal is online at http://snowmanonfire.com and @freeholdhal.

ffirs.indd ix 04/12/12 5:12 PM ACKNOWLEDGMENTS

THANK YOU to the love of my life, April, for your endless support, friendship, and continuing to put up with my nerdy ways. Thank you to my awesome nieces, Indiana Brooke and Austin Margaret. Thank you to the entire WordPress community for your support, friendships, motivation, and guidance. Thank you to Michael, Jason, Freddy, and Hannibal for always lurking in the shadows. Last but not least, thank you to my ridiculous zoo: Lecter, Clarice, and Squeaks the Cat (aka Kitty Galore). Your smiling faces and wiggly butts always put a smile on my face. —Brad Williams

ffirs.indd x 04/12/12 5:12 PM CONTENTS

INTRODUCTION xxi

CHAPTER 1: FIRST POST 1

What Is WordPress? 1 Popularity of WordPress 3 Current State 3 Intersecting the Community 4 WordPress and the GPL 5 Content and Conversation 6 WordPress as a Content Management System 6 Creating Conversation 7 Getting Started 8 Hosting Options 8 Do It Yourself Installation 10 Finishing Up 17 First-Time Administration 17 First Post 19 Summary 20

CHAPTER 2: CODE OVERVIEW 21

Downloading 21 Download Locations 21 Available Formats 22 Release Archive 22 Directory and File Structure 23 WordPress Confi guration 24 wp-confi g.php File 24 Advanced wp-confi g Options 26 .htaccess 31 The .maintenance File 35 wp-content User Playground 36 Plugins 36 Themes 37 Uploads and Media Directory 37 Upgrade Directory 38

ftoc.indd xi 04/12/12 9:18 AM CONTENTS

Custom Directories 38 Summary 39

CHAPTER 3: WORKING WITH WORDPRESS LOCALLY 41

Beneﬁ ts of Working Locally 41 Typical Deployment Cycle 42 Why So Much Process? 42 Tools for Component Administration 43 Getting Your Development Stack 44 Adding WordPress to the Local Install 45 Conﬁ guration Details 46 Managing the Web Server Document Tree 46 Enabling Debug Information 48 Handling Local and Production Database 50 Creating Virtual Local Server Names 50 Local Theme and Plugin Development 53 Deploying Local Changes 53 Summary 55

CHAPTER 4: TOUR OF THE CORE 57

What’s in the Core? 57 Using the Core as a Reference 58 Inline Documentation 59 Finding Functions 60 Exploring the Core 62 Deprecated Functions 65 WordPress Codex and Resources 66 What Is the Codex? 66 Using the Codex 66 Function Reference 67 WordPress APIs 69 Codex Controversy 71 Don’t Hack the Core! 71 Why Not? 71 Alternatives to Hacking the Core 72 Summary 72

CHAPTER 5: THE LOOP 73

Understanding the Loop 74 From Query Parameters to SQL 75

xii

ftoc.indd xii 04/12/12 9:18 AM CONTENTS

Understanding Content in WordPress 76 Putting the Loop in Context 76 Flow of the Loop 77 Template Tags 79 Commonly Used Template Tags 80 Tag Parameters 81 Customizing the Loop 81 Using the WP_Query Object 82 Building a Custom Query 83 Adding Paging to a Loop 85 Using query_posts( ) 86 Using get_posts( ) 87 Resetting a Query 88 More Than One Loop 90 Advanced Queries 91 Global Variables 93 Post Data 93 Author Data 94 User Data 95 Environmental Data 95 Global Variables or Template Tags? 96 Working Outside the Loop 97 Summary 100

CHAPTER 6: DATA MANAGEMENT 101

Database Schema 101 Table Details 103 WordPress Content Tables 104 WordPress Taxonomy Tables 105 WordPress Database Class 106 Simple Database Queries 106 Complex Database Operations 108 Dealing with Errors 110 Direct Database Manipulation 111 Summary 114

CHAPTER 7: CUSTOM POST TYPES, CUSTOM TAXONOMIES, AND METADATA 115

Understanding Data in WordPress 115 What Is a Custom Post Type? 116 Register Custom Post Types 116

xiii

ftoc.indd xiii 04/12/12 9:18 AM CONTENTS

Setting Post Type Labels 121 Working with Custom Post Types 122 Custom Post Type Template Files 123 Special Post Type Functions 124 WordPress Taxonomy 126 Default Taxonomies 126 Taxonomy Table Structure 126 Understanding Taxonomy Relationships 127 Building Your Own Taxonomies 128 Custom Taxonomy Overview 128 Creating Custom Taxonomies 128 Setting Custom Taxonomy Labels 131 Using Your Custom Taxonomy 132 Metadata 133 What Is Metadata? 134 Adding Metadata 134 Updating Metadata 135 Deleting Metadata 135 Retrieving Metadata 136 Summary 137

CHAPTER 8: PLUGIN DEVELOPMENT 139

Plugin Packaging 140 Creating a Plugin File 140 Creating the Plugin Header 140 Plugin License 141 Activating and Deactivating Functions 142 Internationalization 143 Determining Paths 145 Plugin Security 147 Nonces 147 Data Validation and Sanitization 148 Know Your Hooks: Actions and Filters 151 Actions and Filters 151 Popular Filter Hooks 153 Popular Action Hooks 154 Plugin Settings 156 Saving Plugin Options 156 Array of Options 157 Creating a Menu and Submenus 158 Creating an Options Page 160 WordPress Integration 169

xiv

ftoc.indd xiv 04/12/12 9:18 AM CONTENTS

Creating a Meta Box 169 Shortcodes 174 Creating a Widget 175 Creating a Dashboard Widget 179 Creating Custom Tables 180 Uninstalling Your Plugin 182 Creating a Plugin Example 184 Publishing to the Plugin Directory 203 Restrictions 204 Submitting Your Plugin 204 Creating a readme.txt File 204 Setting Up SVN 208 Publishing to the Plugin Directory 209 Releasing a New Version 210 Summary 210

CHAPTER 9: THEME DEVELOPMENT 211

Why Use a Theme? 211 Installing a Theme 212 FTP Installation 212 Theme Installer 213 What Is a Theme? 213 Template Files 214 CSS 214 Images and Assets 214 Plugins 215 Creating Your Own Theme 215 Project Themes vs. Child Themes 215 What to Look for in a Starter Theme 216 Creating Your Own Theme: Getting Started 217 Essential File: Style.css 217 Showing Your Content: Index.php 218 Showing Your Content in Diff erent Ways: Index.php 220 Creating Your Own Theme: DRY 220 Header.php 221 Footer.php 222 Sidebar.php 222 Deviations from the Norm: Conditional Tags 223 Creating Your Own Theme: Content Display 224 Customizing Your Homepage: Front-Page.php 225 Show Your Older Posts by Date: Archive.php 227 Showing Only One Category: Category.php 228

ftoc.indd xv 04/12/12 9:18 AM CONTENTS

Show Posts of a Speciﬁ c Tag: Tag.php 230 Other Archival Templates 231 How to Show a Single Post: Single.php 231 Display a Page: Page.php 232 Display Post Attachments: Attachment.php 233 Template Hierarchy 233 Creating Your Own Theme: Additional Files 235 Handle 404 Errors: 404.php 235 Author.php 236 Comments.php 237 Adding Functionality to Your Templates: Functions.php 238 Search.php 240 SearchForm.php 242 Other Files 242 Custom Page Templates 243 When to Use Custom Page Templates 243 How to Use Custom Page Templates 244 Stock Twenty Eleven Page Templates 245 Other Theme Enhancements 246 Menu Management 246 Widget Areas 248 Post Formats 249 Theme Settings 250 Theme Customizer 251 Theme Hierarchy and Child Themes 251 Premium Themes and Other Theme Frameworks 256 Bones Theme 256 Carrington Theme 257 Genesis Theme 257 Hybrid Core Theme 257 Roots 257 StartBox Theme 258 Thematic Theme 258 Summary 258

CHAPTER 10: MULTISITE 259

What Is Multisite? 259 Multisite Terminology 260 Diff erences 260 Advantages of Multisite 261 Enabling Multisite 261 Working in a Network 262

xvi

ftoc.indd xvi 04/12/12 9:18 AM CONTENTS

Network Admin 263 Creating and Managing Sites 263 Working with Users and Roles 264 Themes and Plugins 264 Settings 265 Domain Mapping 265 Coding for Multisite 265 Blog ID 265 Common Functions 266 Creating a New Site 270 Network Admin Menus 274 Multisite Options 276 Users in a Network 282 Super Admins 285 Network Stats 286 Multisite Database Schema 287 Multisite-Speciﬁ c Tables 287 Site-Speciﬁ c Tables 287 Summary 288

CHAPTER 11: CONTENT AGGREGATION 289

Getting Noticed 290 Social Media Buttons 291 Feeding WordPress Upstream 292 Buttons, Badges, or Both? 292 Simple Social Networking Badges 293 Collecting External Content 294 Integrating a YouTube Video 295 Integrating Twitter 296 Google Maps 298 Integrating Facebook 299 Generic XML Data 299 Transients 301 Advertising 303 Monetizing Your Site 303 Setting Up Advertising 304 Privacy and History 307 Summary 308

CHAPTER 12: CRAFTING A USER EXPERIENCE 309

User Experience Principles 309 Consistent Navigation 310 xvii

ftoc.indd xvii 04/12/12 9:18 AM CONTENTS

Visual Design Elements 312 Making Content Easy to Find 314 Site Load Times 314 Using JavaScript 316 Usability and Usability Testing 316 Structuring Your Information 318 Getting Your Site Found 320 Duplicate Content 321 Trackbacks and Pings 323 Tags and Content Sharing Sites 324 How Web Standards Get Your Data Discovered 324 Semantic HTML 324 Valid HTML 326 Microformats 327 HTML5 329 CSS3 330 Searching Your Own Site 331 Weaknesses of the Default Search 331 Alternatives and Plugins to Help 332 Mobile Access and Responsive Web Design 334 Leave It Alone 334 Lightweight Mobile 335 Responsive Design 335 Summary 336

CHAPTER 13: STATISTICS, SCALABILITY, SECURITY, AND SPAM 337

Statistics Counters 337 AWStats 338 Google Analytics 340 JetPack by WordPress.com 342 Cache Management 343 WordPress System Complexity 344 Web Server Caching and Optimization 345 WordPress Object Caching 347 Transient Caches 347 MySQL Query Cache 348 Load Balancing Your WordPress Site 349 Dealing with Spam 350 Comment Moderation and CAPTCHAs 350 Automating Spam Detection 351 Securing Your WordPress Site 352

xviii

ftoc.indd xviii 04/12/12 9:18 AM CONTENTS

Staying Up-to-Date 352 Hiding WordPress Version Information 353 Limit Login Attempts 354 Using Good Passwords 354 Changing Your Table Preﬁ x 354 Moving Your Conﬁ guration File 354 Moving Your Content Directory 355 Using the Secret Key Feature 355 Forcing SSL on Login and Admin 356 Apache Permissions 356 MySQL Credentials 357 Recommended Security Plugins 357 Using WordPress Roles 360 Subscriber Role 361 Contributor Role 361 Author Role 361 Editor Role 361 Administrator Role 362 Super Admin Role 362 Role Overview 362 Extending Roles 363 Summary 364

CHAPTER 14: WORDPRESS AS A CONTENT MANAGEMENT SYSTEM 365

Defi ning Content Management 365 Workfl ow and Delegation 367 User Roles and Delegation 367 Workfl ow 368 Content Organization 370 Theme and Widget Support 370 Homepages 372 Featured Content Pages 373 Content Hierarchy 376 Interactivity Features 379 Forums 379 Forms 379 E-Commerce 380 Other Content Management Systems 380 WordPress Integration 381 Where Not to Use WordPress 381 Summary 382

xix

ftoc.indd xix 04/12/12 9:18 AM CONTENTS

CHAPTER 15: WORDPRESS IN THE ENTERPRISE 383

Is WordPress Right for Your Enterprise? 383 When WordPress Isn’t Right for You 385 Scalability 386 Performance Tuning 386 Caching 388 Regular Maintenance 388 Hardware Scaling 389 Integration with Enterprise Identity Management 391 LDAP and Active Directory 391 OpenID and OAuth 392 Content Integration via Feeds 393 Summary 395

CHAPTER 16: WORDPRESS DEVELOPER COMMUNITY 397

Contributing to WordPress 397 Understanding Trac 398 Working on the Core 401 Submitting Plugins and Themes 402 Documentation 402 Sister Projects 403 BuddyPress 403 bbPress 403 Future Projects 403 Resources 404 Codex 404 Support Forums 404 WordPress Chat 405 Mailing Lists 405 External Resources 406 WordCamp and Meetups 407 WordPress.TV 407 Theme/Plugin Directories 407 WordPress Ideas 407 WordPress Development Updates 408 Make WordPress.org 408 WordPress Podcasts 408 WordPress News Sites 409 Summary 410

INDEX 411

ftoc.indd xx 04/12/12 9:18 AM INTRODUCTION

DEAR READER, Thank you for picking up this book. WordPress is the most popular self-hosted website software in use today. It is available as an open source project, licensed under the GPL, and is built largely on top of the MySQL database and PHP programming language. Any server environment that supports that simple combination can run WordPress, making it remarkably portable as well as simple to install and operate. You don’t need to be a systems administrator, developer, HTML expert, or design aesthete to use WordPress. On the other hand, because WordPress has been developed using a powerful set of Internet standard platforms, it can be extended and tailored for a wide variety of applications. WordPress is the publishing mechanism underneath thousands of individual blog voices and the engine that powers high-volume, high-profi le sites such as CNN’s websites and blogs. It was designed for anyone comfortable navigating a browser, but is accessible to web designers and developers as well. Given this range of applications and capabilities, it can prove hard to know where to start if you want to make use of the power of WordPress for your specifi c purposes. Should you fi rst study the database models and relationships of content and metadata, or the presentation mechanics that generate the HTML output? This book was designed for readers to develop a knowledge of WordPress from the inside out, focusing on the internal structure and fl ow of the core code as well as the data model on which that code operates. Knowing how something works often makes you more adept at working with it, extending it, or fi xing it when it breaks. Just as a race car driver benefi ts from a fundamental knowledge of combustion engines, aerodynamics, and the mechanics of automobile suspension, someone driving WordPress through its full dynamic range will be signifi cantly more adept once acquainted with the underlying software physics.

WHO THIS BOOK IS FOR

It was the dichotomy between the almost trivial effort required to create a WordPress-based website and publish a “fi rst post” to the world and the much more detailed, broad understanding required to effect mass customization that led us to write this book. Many books on the market provide guidance to beginning bloggers by walking you through the typical functions of creating, confi guring, and caring for your WordPress site. Our goal was to bridge the gap between an expert PHP developer who is comfortable reading the WordPress Codex in lieu of a manual and the casual WordPress user creating a public persona integrated with social networking sites and advertising services, with a tailored look and feel. In short, we hope to appeal to a range of developers, from the person looking to fi ne-tune a WordPress theme to a more advanced developer with a plugin concept or who is using WordPress in a large enterprise integrated into a content management system. We do this by exploring WordPress from the inside out. Our goal for this book is to describe the basic operation of a function, and

flast.indd xxi 04/12/12 9:18 AM INTRODUCTION

then offer guidance and examples that highlight how to take it apart and reassemble that function to fi t a number of needs. WordPress users who are not hardened PHP developers may want to skim through the developer-centric section, whereas coders looking for specifi c patterns to implement new WordPress functionality can start in the middle and work toward the end.

WHAT THIS BOOK COVERS

This book is divided into three major sections: Chapters 1 through 4 are an overview of the WordPress system, its major functional elements, and a top-level description of what happens when a WordPress-generated web page is displayed. Chapters 5 through 9 build on this foundation and dive into the core of WordPress, describing internal code fl ow and data structures. This middle section is strongly developer-oriented, and describes how to extend WordPress through plugins and customize it via themes. The last section, Chapters 10 through 16, combines a developer view of user experience and optimization with the deployer requirements for performance, security, and enterprise integration.

HOW THIS BOOK IS STRUCTURED

The following is a detailed chapter-by-chapter overview of what you can expect to fi nd in this book. Chapter 1, “First Post,” contains a brief summary of the history of the WordPress software core, explores some popular hosting options, why community matters in a content-centric world, and concludes with the basics of do-it-yourself WordPress installation and debugging. Chapter 2, “Code Overview,” starts with the mechanics of downloading the WordPress distribution and describes its basic contents and fi lesystem layout. A top-to-bottom code fl ow walks you from an index or specifi c post URL, through the process of selecting posts, assembling content, and generating the displayed HTML. This chapter is a map for the more detailed code tours in the developer-focused section. Chapter 3, “Working with WordPress Locally,” covers the many benefi ts to working with WordPress on your local computer. This chapter also reviews the various setups for local development on a Microsoft Windows or Apple OSX computer. Finally you’ll cover how to deploy your local changes to a remote server using various deployment methods. Chapter 4, “Tour of the Core,” examines the essential PHP functions comprising the basic WordPress engine. It serves as an introduction to the developer-focused middle section of the book and also lays the foundation for the deployment-, integration-, and experience-focused chapters in the last section. This chapter also covers using the core as a reference guide, and why it is best not to hack the core code to achieve desired customizations. Chapter 5, “The Loop,” is the basis for the developer-centric core of this book. The WordPress main loop drives the functions of creating and storing content in the MySQL database, as well as extracting appropriate chunks of it to be sorted, decorated, and nested under banners or next to sidebars, in

xxii

flast.indd xxii 04/12/12 9:18 AM INTRODUCTION

both cases generating something a web browser consumes. This chapter disassembles those processes of creating, saving, and publishing a new post as well as displaying content that has been stored in the WordPress MySQL databases. The underlying database functions and the management of content metadata are covered in more detail to complete a thorough view of WordPress’ internal operation. Chapter 6, “Data Management,” is the MySQL-based counterpart to Chapter 5. The core functions create, update, and manipulate entries in multiple MySQL database tables, and this chapter covers the database schema, data and metadata taxonomies used, and the basic relations that exist between WordPress elements. It also includes an overview of the basic query functions used to select and extract content from MySQL, forming a basis for extensions and custom code that needs to be able to examine the individual data underlying a WordPress site. Chapter 7, “Custom Post Types, Custom Taxonomies, and Metadata,” explores the different types of content and associated data in WordPress. You’ll cover how to register and work with custom post types for creating custom content in WordPress. Custom taxonomies are also dissected, diving into the various setups with examples. Finally you’ll cover post metadata, and the proper ways to store arbitrary data against posts in WordPress. Chapter 8, “Plugin Development,” starts with the basic plugin architecture and then explores the hook, action, and fi lter interfaces that integrate new functionality around the WordPress core. This chapter demonstrates the interposition of functions into the page composition or content management streams and how to save plugin data. Examples of building a plugin using a simple framework outline the necessary functionality of any plugin. This chapter also covers creation of widgets, simpler-to-use plugins that typically add decoration, additional images, or content to a sidebar; many plugins also have a widget for easier management. Publishing a plugin to the WordPress repository and pitfalls of plugin confl ict round out the discussion of WordPress’ functional extensions. Chapter 9, “Theme Development,” is the display and rendering counterpart to Chapter 8. Plugins add new features and functions to the core, whereas themes, CSS and page templates change the way that content is shown to readers. Starting with a basic theme, this chapter covers writing a theme, building custom page templates, menu management, widget areas, post formats, theme installation, and how thematic elements are used by the functions described in previous chapters. This chapter ends the deep developer-focused middle section of the book. Chapter 10, “Multisite,” explores the popular Multisite feature of WordPress. You’ll learn the advantages of running your own Multisite network, how to properly install Multisite, working in a network, creating sites and users, managing themes and plugins, and even domain mapping. The last part of the chapter explores coding for Multisite and the various functions and methods available for use. Chapter 11, “Content Aggregation,” looks at WordPress from a services point of view. If a website represents your public persona or online presence, it has to pull content from a variety of tools and content sources. This chapter delves into web services interfaces, WordPress APIs, feeds into and out of WordPress, and making WordPress entries show up in Facebook pages.

xxiii

flast.indd xxiii 04/12/12 9:18 AM INTRODUCTION

Chapter 12, “Crafting the User Experience,” looks at a WordPress installation from the perspective of a regular or potential reader. Usability, testing, and the ease of fi nding information within a WordPress website form the basics, with added emphasis on web standards for metadata and search engine optimization so content can be found through an appropriate Google search. Whereas Chapter 11 covers pulling external content into your WordPress instance, this chapter shows how to get your content to show up elsewhere on the Web. Alternatives for adding search functionality, one of WordPress’ weaknesses, are discussed, along with content accessibility and delivery to mobile devices. Chapter 13, “Statistics, Scalability, Security, and Spam,” deals with good and bad popularity. Keeping a WordPress installation safe from inevitable comment spammers as well as malicious attackers is a key part of confi guration and management, and this chapter covers the more popular security and anti-spam plugins and features. Traffi c analysis tools indicate how well certain content types, functions, ad campaigns, promotions, or links are driving readership and how this informs traffi c management. Chapter 14, “WordPress as a Content Management System,” goes beyond blogging to examples of WordPress as a system for managing the life cycle, integration, and distribution of networked content. Chapter 15, “WordPress in the Enterprise,” tackles issues of scale and integration. WordPress may address defi ciencies in “enterprise scale” content management tools, and building on the mechanisms covered in Chapter 12, this chapter shows how to use WordPress with a variety of enterprise facilities ranging from identity management to Microsoft ASP.NET services. Chapter 16, “WordPress Developer Community,” is an introduction to contributing to the WordPress ecosystem by working on the core, submitting plugins or themes, adding to the documentation canon, and assisting other developers. An overview of WordPress sister projects such as bbPress for forums is provided along with a brief summary of other developer resources and a glossary of WordPress-context sensitive terms.

WHAT YOU NEED TO USE THIS BOOK

You’ll need at least a rudimentary understanding of HTML and some knowledge of cascading style sheets (CSS) to make use of the theme and user experience sections of the book. Experience in writing and debugging PHP code is a prerequisite for more advanced developer sections, although if you’re just going to make changes based on the samples in this book, you can use the code as a template and learn on the fl y. A basic knowledge of databases, especially the syntax and semantics of MySQL, is in order to make the most out of the chapter on data management as well as develop plugins that need to save data. It’s helpful to have an interactive development environment in which to view PHP code, or PHP code sprinkled through HTML pages. Choosing a set of developer tools often borders on religion and deep personal preference (and we know plenty of coders who believe that vi constitutes a development environment). Some of the more user-friendly tools will make walking through the WordPress code easier if you want to see how functions used in the examples appear in the core.

xxiv

flast.indd xxiv 04/12/12 9:18 AM INTRODUCTION

Most important, if you want to use the code samples and examples in this book, you’ll need a WordPress website in which to install them. Chapter 1 covers some basic WordPress hosting options as well as the simple mechanics of downloading the components, and installing WordPress on a desktop or test machine for debugging and closer inspection. Finally, some people might argue that to really take advantage of WordPress you need to be able to write, but that ignores the basic beauty of the WordPress platform: it takes the power of the printing press to an individual level. This book isn’t about what you say (or might say); it’s about how you’re going to get those ideas onto the web and how the world will see them and interact with your blog. The source code for the samples is available for download from the Wrox website at: www.wrox.com/remtitle.cgi?isbn=9781118442272

CONVENTIONS

To help you get the most from the text and keep track of what’s happening, we’ve used a number of conventions throughout the book.

WARNING Boxes like this one hold important, not-to-be forgotten information that is directly relevant to the surrounding text.

NOTE Notes indicate notes, tips, hints, tricks, or and asides to the current discussion.

As for styles in the text: ➤ We italicize new terms and important words when we introduce them. ➤ We show fi le names, URLs, and code within the text like so: persistence.properties. ➤ We present code in two different ways:

We use a monofont type with no highlighting for most code examples.

We use bold to emphasize code that's particularly important in the present context.

SOURCE CODE

As you work through the examples in this book, you may choose either to type in all the code manually, or to use the source code fi les that accompany the book. All the source code used in this book is available for download at www.wrox.com. Specifi cally for this book, the code download is on the Download Code tab at: www.wrox.com/remtitle.cgi?isbn=9781118442272

xxv

flast.indd xxv 04/12/12 9:18 AM INTRODUCTION

You can also search for the book at www.wrox.com by ISBN. A complete list of code downloads for all current Wrox books is available at www.wrox.com/dynamic/books/download.aspx.

NOTE Because many books have similar titles, you may fi nd it easiest to search by ISBN, which is 978-1-118-44227-2.

At the beginning of each chapter for which there is downloadable code, we’ve provided a reminder of the URL at which you can fi nd the code fi les. Throughout each chapter, you’ll also fi nd references to the code fi le names in listing titles or the text.

Most of the code on www.wrox.com is compressed in a .ZIP, .RAR archive, or similar archive format appropriate to the platform. Once you download the code, just decompress it with your preferred compression tool.

ERRATA

We make every effort to ensure that there are no errors in the text or in the code. However, no one is perfect, and mistakes do occur. If you fi nd an error in one of our books, like a spelling mistake or faulty piece of code, we would be very grateful for your feedback. By sending in errata, you may save another reader hours of frustration, and at the same time, you will be helping us provide even higher quality information. To fi nd the errata page for this book, go to: www.wrox.com/remtitle.cgi?isbn=9781118442272 And click the Errata link. On this page you can view all errata that has been submitted for this book and posted by Wrox editors.

If you don’t spot “your” error on the Book Errata page, go to www.wrox.com/contact/techsup- port.shtml and complete the form there to send us the error you have found. We’ll check the information and, if appropriate, post a message to the book’s errata page and fi x the problem in subsequent editions of the book.

P2P.WROX.COM

For author and peer discussion, join the P2P forums at http://p2p.wrox.com. The forums are a web-based system for you to post messages relating to Wrox books and related technologies and interact with other readers and technology users. The forums offer a subscription feature to e-mail you topics of interest of your choosing when new posts are made to the forums. Wrox authors, editors, other industry experts, and your fellow readers are present on these forums.

xxvi

flast.indd xxvi 04/12/12 9:18 AM INTRODUCTION

At http://p2p.wrox.com, you will fi nd a number of different forums that will help you, not only as you read this book, but also as you develop your own applications. To join the forums, just follow these steps: 1. Go to http://p2p.wrox.com and click the Register link. 2. Read the terms of use and click Agree. 3. Complete the required information to join, as well as any optional information you wish to provide, and click Submit. 4. You will receive an e-mail with information describing how to verify your account and complete the joining process.

NOTE You can read messages in the forums without joining P2P, but in order to post your own messages, you must join the forum.

Once you join, you can post new messages and respond to messages other users post. You can read messages at any time on the web. If you would like to have new messages from a particular forum e-mailed to you, click the Subscribe to this Forum icon by the forum name in the forum listing. For more information about how to use the Wrox P2P, be sure to read the P2P FAQs for answers to questions about how the forum software works, as well as many common questions specifi c to P2P and Wrox books. To read the FAQs, click the FAQ link on any P2P page.

xxvii

flast.indd xxvii 04/12/12 9:18 AM flast.indd xxviii 04/12/12 9:18 AM 1 First Post

WHAT’S IN THIS CHAPTER?

➤ Appreciating the provenance of the WordPress platform ➤ Choosing a suitable platform for your WordPress installation ➤ Downloading, installing, and performing basic conﬁ guration of WordPress ➤ Diagnosing and resolving common installation problems If displaying “Hello World” on an appropriate device defi nes minimum competence in a programming language, generating your fi rst post is the equivalent in the online publishing world. This chapter provides a brief history of WordPress and then explores several options for hosting a WordPress installation. Common miscues and misperceptions along with their resolutions round out the chapter and put you on the edge of publishing your wit and wisdom. Once you’ve installed, confi gured, and completed the bare-bones administration, you’re ready to take advantage of the code walk-throughs and detailed component descriptions in later chapters. Of course, if you already have a functional WordPress website, you can skip this chapter, and dive in headfi rst to explore the core code in Chapter 2, “Code Overview.”

WHAT IS WORDPRESS?

WordPress is one of the most popular open source content management systems available, with global and vibrant user, developer, and support communities. While it can be compared to TypePad, Moveable Type, Google’s Blogger, and the Apache Roller project as a user-generated content workhorse, WordPress distinguishes itself with a broad array of hosting options, functional extensions (plugins), and aesthetic designs and elements (themes).

c01.indd 1 12/6/12 1:11 AM 2 ❘ CHAPTER 1 FIRST POST

With the rise of self-publishing, low-cost web hosting, and freely available core components like the MySQL database, blogging software followed the same trend as most other digital technologies, moving from high-end, high-cost products to widely available, low-cost consumer or “hobbyist” systems. WordPress isn’t simply about creating a blog so that you can have a digital diary attached to your vanity URL; it has evolved into a full-fl edged content management system used by individuals and enterprises alike. This section takes a brief tour through the early history of WordPress and brings you up to speed on the current release and user community. WordPress started similarly to many other popular open source software packages: Some talented developers saw a need to create a powerful, simple tool based on an existing project licensed under the GPL. Michel Valdrighi’s b2/cafelog system provided the starting point, and WordPress was built as a fork of that code base by developers Matt Mullenweg and Mike Little. WordPress fi rst appeared in 2003 and was also built on the MySQL open source database for persisting content with PHP as the development platform. Valdrighi remains a contributor to the project, which is thriving as it has a growing and interested community of users and developers on a growing and interested community of users and developers. As with other systems written in PHP, it is self-contained in the sense that installation, confi guration, operation, and administration tasks are all contained in PHP modules. WordPress’s popularity has been driven in part by its simplicity, with the phrase “fi ve-minute installation” making appearances in nearly every description or book about WordPress. Beyond getting to a fi rst post, WordPress was designed to be extended and adaptable to the different needs of different people. WordPress today is supported by a handful of core developers and many key contributors. Mike Little runs the WordPress specialty shop zed1.com and he contributes the occasional patch to the code. Matt Mullenweg’s company, Automattic, continues to operate the wordpress.com hosting service as well as fund development of related content and site management tools, including Akismet, multi-site WordPress, and Gravatar. Akismet is a robust, Automattic-hosted spam detection and protection service with a statistically (and incredibly) low failure-to-detect rate. Previously known as WordPress MU, multi-site WordPress functions are at the heart of the wordpress.com hosting system and are now merged into the main WordPress source tree. Gravatar dynamically serves images tied to e-mail addresses, providing a hosted icon with a variety of display options. Think of it as a service to make hot-linking your profi le picture technically and socially acceptable. As a content management system, the WordPress system defi nition doesn’t stop at time-serialized posts with comments. BuddyPress is a set of themes and plugins that extends WordPress into a functional social networking platform, allowing registered users to message and interact with each other, again with all content managed within the WordPress framework. Similarly, bbPress is a PHP- and MySQL-based system designed for forums (bulletin boards) that is distinct from WordPress but is commonly integrated with it. Chapter 16, “WordPress Developer Community,” covers some of the WordPress adjunct systems in more detail, but they’re included here to provide a sense of how WordPress has expanded beyond a basic single-user–oriented tool. At the same time, the authors are not endorsing or making a commercial for Automattic, but delving into the guts of WordPress without a spin of the propeller hat toward Mullenweg and Little is somewhere between incorrigible and bad community behavior.

c01.indd 2 12/6/12 1:11 AM Popularity of WordPress ❘ 3

POPULARITY OF WORDPRESS

This book is based on the WordPress 3.5 major release. Each successive release of WordPress has included improvements in the administration and control functions (Dashboard); backup, export, and import functions; and installation and upgrade features. Even if you start with a slightly down-rev version of WordPress, you’ll be able to bring it up to the current release and maintain the freshness of your install. Install and upgrade paths are touched on later in this chapter. But just how popular is WordPress?

Current State Interest in WordPress and WordPress usage is booming. You’re holding in your hands a testament to that. Just 3 years ago, very few WordPress books were available. Now this second edition has been published. “Popular” is always a subjective metric, but statistics add some weight to those perceptions. According to Automattic, as of 2011, over 100,000 new WordPresses are created every day (http://en.wordpress.com/stats/). That includes sites using WordPress for content management, blogging, and personal rants, and has to be discounted by those of you who have multiple WordPress installations to their names, but even with that order of magnitude estimate, WordPress is immensely popular. Automattic cites nearly 74 million WordPress websites globally with about half of them hosted at WordPress.com (http://en.wordpress.com/stats/). In the previous edition of this book, that number was at only 5 million sites. In 2008, the offi cial WordPress plugin repository hosted over 6,300 plugins, double the number from 2007. At the time of this writing, the number of plugins now tops 19,000 (http://wordpress.org/news/2012/05/ plugins-refreshed/). There are over 1,500 unique themes in the offi cial WordPress theme repository, which does not include all the commercial theme vendors and independent developers creating their own custom themes. The combinations of plugins and themes require scientifi c notation to represent in complexity, but at the same time, they’re all equally simple to locate, integrate, and use. That’s the result of a solid architecture and an equally solid community using it. In short, the ecosystem surrounding WordPress is alive and thriving. In August 2011, Matt Mullenweg presented the current state of WordPress use as well as results from the fi rst-ever WordPress survey at the San Francisco WordCamp. The WordPress survey is similar to a census of the WordPress community at large and how people use WordPress every day. This includes independent web developers, corporate users, and hobbyists providing a great cross-section of the larger WordPress population. The following highlights demonstrate how active and prevalent WordPress is on the global Internet: ➤ Nearly 15 percent of the top 1 million visited websites use WordPress. ➤ On average, 22 of every 100 new websites run WordPress. ➤ More than 200 million plugins have been downloaded from the plugin repository. ➤ 18,000 individuals responded to the survey representing over 170,000 websites. Mullenweg’s State of the Word keynote can be seen at WordPress.tv.

c01.indd 3 12/6/12 1:11 AM 4 ❘ CHAPTER 1 FIRST POST

Today, WordPress powers many large media companies’ websites or portions thereof, including CNN’s blogs, the Wall Street Journal’s All Things D, Reuters, Forbes, and the irreverent but snowclone-driven icanhazcheeseburger.com. (If you looked for a back story on “snowclone,” apologies, but that’s also the joy of discovering new facts in a culture of participatory media.) WordPress is used by Fortune 500 companies such as GM, UPS, and Sony. WordPress is a viable choice for a range of users, from international conglomerates to major recording artists to huge media publishing companies.” Some need reassurance before choosing WordPress and focus on which big boys are using it, you can fi nd a list online at the WordPress Notable Users showcase (http://en.wordpress.com/notable-users/). But the simplicity, ease of use, and ultimately the power of the plugins and themes make WordPress suitable for your mom’s family information website, your local elementary school teacher’s class- room newsletter, and the hobbyist. These are truly some of the WordPress success stories of today and these widely accessible, more narrowly popular websites are what makes WordPress popular. WordPress is adaptable and will be as simple or complex as you need it to be. Empowering “lower tech” users to be web publishers and then spreading the word (pun intended) to their family and friends about how easy WordPress is to use have fueled this explosive growth and adoption.

Where do you get started? wordpress.org is the home for the current released and in-development versions of the code. Click through to wordpress.org/extend for a starting point in fi nding plugins, themes, and wish lists of ideas and features to be implemented.

wordpress.com has both free and paid hosting services. Over at wordpress.org/hosting you’ll fi nd a list of hosting providers that support WordPress and often include some additional fi rst-time installation and confi guration support in their packaging of the code for delivery as part of their hosting services.

Intersecting the Community WordPress thrives and grows based on community contributions in addition to sheer usage. Like high school gym class, participation is the name of the game, and several semi-formal avenues along which to channel your efforts and energies are available. WordCamp events are community-hosted and locally operated, and now happen in dozens of cities around the world. Offi cial WordCamps are listed on wordcamp.org, but you’ll do just as well to search for a WordCamp event in a major city close to you. WordCamps occur nearly every weekend with bloggers, photographers, writers, editors, developers, and designers of all experience and skill levels counted among their attendees. WordCamps are a low-cost introduction to the local community and often a good opportunity to meet WordPress celebrities. Visit wordcamp.org to fi nd the next WordCamp. Less structured but more frequently convened than WordCamps are WordPress Meetups, comprising local users and developers in nearly 200 (up from the 40 mentioned in the fi rst edition of this book) cities. You’ll need a meetup.com account, but once you’re registered, you can check on locations and timetables at wordpress.meetup.com to see when and where people are talking about content management.

A rich, multi-language documentation repository is hosted at codex.wordpress.org. The WordPress Codex, with all due respect to the term reserved for ancient handwritten manuscripts,

c01.indd 4 12/6/12 1:11 AM Popularity of WordPress ❘ 5

represents the community-contributed tips and tricks for every facet of WordPress, from installation to debugging. If you feel the urge to contribute to the WordPress documentation, register and then write to your heart’s content in the WordPress Codex. Hopefully you’ll fi nd this book a cross between a companion and a travel guide to the Codex. Finally, mailing lists (and their archives) exist for various WordPress contributors and communities. A current roster is available online at codex.wordpress.org/Mailing_Lists; of particular interest may be the wp-docs list for Codex contributors and the wp-hackers list for those who work on the WordPress core and steer its future directions.

WordPress and the GPL WordPress is licensed under the Gnu Public License (GPL) version 2, contained in the license.txt fi le that you’ll fi nd in the top-level code distribution. Most people don’t read the license and simply understand that WordPress is an open source project; however, pockets of corporate legal departments still worry about the viral component of a GPL license and its implications for additional code or content that gets added to, used with, or layered on top of the original distribution. Much of this confusion stems from liberal use of the words “free” and “copyright” in contexts where they are inappropriately applied. The authors of this book are not lawyers — nor do they play them on the Internet or on television — and if you really want to understand the nuances of copyright law and what constitutes a “conveyance” of code, pick up some of Lawrence Lessig’s or Cory Doctorow’s work in those areas. This section is included to minimize the concerns of IT departments who may be dissuaded from using WordPress as an enterprise content management system by overly zealous legal teams. Don’t let this happen to you; again, if WordPress is acceptable to CNN and the Wall Street Journal, two companies that survive on the copyrights granted to their content, it probably fi ts within the legal strictures of most corporate users as well. The core tenet of the GPL ensures that you can always get the source code for any distribution of GPL-licensed software. If a company modifi es a GPL-licensed software package and then redistributes that newer version, it has to make the source code available as well. This is the “viral” nature of GPL at work; its goal is to make sure that access to the software and its derivatives is never reduced in scope. If you plan on modifying the WordPress core and then distributing that code, you’ll need to make sure your changes are covered by the GPL and that the code is available in source code form. Given that WordPress is written in PHP, an interpreted language, distributing the software and distributing the source code are effectively the same action. Following are some common misperceptions and associated explanations about using WordPress in commercial situations. ➤ “Free software” means you can’t commercialize its use. You can charge people to use your installation of WordPress, or make money from advertisements running in your website, or use a WordPress content management platform as the foundation of an online store. That’s how wordpress.com works; it also enables Google to charge advertisers for using their Linux-based services. You can fi nd professional quality WordPress themes with non-trivial price tags, or you can pay a hosting provider hundreds or even thousands of dollars a year to run your MySQL, PHP, Apache, and WordPress software stack; both involve commercialization of WordPress.

c01.indd 5 12/6/12 1:11 AM 6 ❘ CHAPTER 1 FIRST POST

➤ If you customize the code to handle your own {content types, security policies, obscure navigational requirements} you’ll have to publish those changes. You’re only required to make the source code available for software that you distribute. If you choose to make those changes inside your company, you don’t have to redistribute them. On the other hand, if you’ve made some improvements to the WordPress core, the entire community would benefi t from them. Getting more staid employers to understand the value of community contribution and relax copyright and employee contribution rules is sometimes a bit challenging, but the fact that you had a solid starting point is proof that other employers made precisely that set of choices on behalf of the greater WordPress community. ➤ The GPL will “infect” content that you put into WordPress. Content — including graphic elements of themes, posts, and pages managed by WordPress — is separated out from the WordPress core. It’s managed by the software, but not a derivative of or part of the software. Themes, however, are a derivative of the WordPress code and therefore also fall under the GPL, requiring you to make the source code for the theme available. Note that you can still charge for the theme if you want to make it commercially available. Again, the key point here is that you make the source code available to anyone who uses the software. If you’re going to charge for the use of a theme, you need to make the source code available under the GPL as well, but as pointed out previously, users installing the theme effectively get the source code. More important than a WordPress history lesson and licensing examination are the issues of what you can do with WordPress and why you’d want to enjoy its robustness. The next section looks at WordPress as a full-fl edged content management system, rather than simply a blog editing tool.

CONTENT AND CONVERSATION

Multiple linear feet of shelves in bookstores are fi lled with volumes that will improve your writing voice, literary style, blogging techniques, and other aspects of your content creation abilities. One of the goals of this book is to defi ne the visual, stylistic, and context management mechanisms you can build with WordPress to shape vibrant user communities around your content. That context stimulates conversation with your readers. It’s not just about the words in each post, or even if you’re an interesting writer. How will people fi nd you? How will you stand out in the crowd? How do you put your own imprint on your site, and personalize it for whatever purpose: personal, enterprise, community, or commercial?

WordPress as a Content Management System Blogging systems have their roots in simple content management operations: Create a post, persist it in stable storage such as a fi lesystem or database, and display the formatted output based on some set of temporal or keyword criteria. As the richness and types of content presented in blog pages expanded, and the requirements for sorting, searching, selecting, and presenting content grew to include metadata and content taxonomies, the line between vanilla, single-user–targeted blogging software and enterprise-grade content management systems blurred. Content management systems (CMS) handle the creation, storage, retrieval, description or annotation, and publication or display of a variety of content types. CMS also covers workfl ow

c01.indd 6 12/6/12 1:11 AM Content and Conversation ❘ 7

tasks, typically from an editorial or publishing perspective, but also including actions such as approval and marking content for additional editing or review. The WordPress Dashboard provides those elements of workfl ow management and editorial control. WordPress isn’t the only open source content management system in widespread use today; the Drupal and Joomla projects are equally popular choices. Drupal and Joomla start from the perspective of managing content repositories; they handle a variety of content types, multiple authors in multiple roles, and delivering the content to a consumer that requests it. WordPress is at its heart a blogging system, and the end focus is on displaying content to a reader. Although areas of functional overlap exist, you can integrate WordPress with other content management systems, a process covered in detail in Chapter 14. WordPress has established itself as a bona fi de content management system through its design for extensibility and the separation of content persistence from content display. Taking some liberties with the Model-View-Controller design pattern, WordPress separates the MySQL persistence layer as a data model, the theme-driven user interface and display functions, and the plugin architecture that interposes functionality into the data to presentation fl ow. Most important, WordPress stores content in raw form, as input by the user or an application posting through the WordPress APIs. Content is not formatted, run through templates, or laid out until the page is rendered, yielding immense power to the functions that generate the actual HTML. At the same time, the data model used by WordPress uses a rich set of tables to manage categories (taxonomies), content tags (folk- sonomies), author information, comments, and other pieces of cross-reference value. The WordPress database schema that makes this possible is explored in Chapter 6. Although that design gives WordPress incredible power and fl exibility as a content management system, it also requires knowledge of how those data persistence and control fl ows are related (it was a search for such a dissection of WordPress in functional terms that got us together to write this book).

Creating Conversation

“Conversation is king; content is just something to talk about.” — Cory Doctorow

A robust CMS is measured by the utility of its content. Even the richest content types and most well- managed processes are of low return if nobody actually consumes the outputs. It’s not suffi cient to install blogging software, write a few posts, and hope the world shows up on your virtual doorstep; you need to create what Tim O’Reilly calls an “architecture of participation.” Social networking, advertising, feeds, and taking steps to ensure your site shows up in search engine results will drive readers to your site; the design, branding, and graphic elements coupled with the quality of your content will encourage them to take the steps toward active participation. Look at the problem from the perspective of a reader: in a world of tens of millions of websites (many of which have a “fi rst post” and not much else) how will you be found, heard, and echoed? Your Twitter followers should want to read your site, and your WordPress site can update your Twitter feed. Conversely, your Twitter updates may appear in your WordPress sidebar, marrying the ultra-short content timeline to the more thoughtful one. If you’re active on Facebook, you can import entries into a public fi gure page and Facebook readership will drive traffi c back to your

c01.indd 7 12/6/12 1:11 AM 8 ❘ CHAPTER 1 FIRST POST

website. If you cover specifi c, detailed, or arcane areas in your writing, Google searches for those terms should direct readers to you, where they’ll join the conversation. Chapter 11, “Content Aggregation,” covers getting content into WordPress from social media and other content systems, and Chapter 12, “Crafting a User Experience,” looks at how your WordPress content can be more broadly distributed.

GETTING STARTED

Before any serious work on presentation, style, or content begins, you need a home for your website (despite the previous discussion about WordPress and content management systems, you’ll refer to your website and the actual WordPress installation that implements it interchangeably, mostly for convenience and brevity). Factors affecting your choice include: ➤ Cost — Free hosting services limit your options as a developer, and frequently preclude you from generating money from advertising services. More expensive offerings may include better support, higher storage or bandwidth limits, or multiple database instances for additional applications. ➤ Control — What tools are provided for you to manage your MySQL database, fi les comprising the WordPress installation, and other content types? If you want to be able to muck around at the SQL level, or manage MySQL through a command-line interface, you should ensure your hosting provider supports those interfaces. ➤ Complexity — You can install the Apache web server with a PHP interpreter, MySQL, and the WordPress distribution yourself, but most hosting providers have wrapped up the installation process so that some of the rough edges are hidden from view. If you expect to need technical support on the underlying operating system platform, fi nd a provider (including your own IT department) that provides that support in a reasonable time frame. This section takes a quick look at some hosting options, walks you through the basics of a do-it- yourself installation, and concludes with an overview of the ways in which WordPress and MySQL choose to ignore each other when installation goes into the weeds.

Hosting Options Three broad categories of WordPress hosting exist, each with trade-offs between administrative complexity and depth of control. The easiest and most popular is to use wordpress.com, a free hosting service run by Automattic using the multi-site version of WordPress (originally WordPress MU). You can install themes and plugins through the Dashboard but you can only enable or disable the choices that come preinstalled. Further, you won’t have access to the underlying MySQL databases and core code, or be able to integrate WordPress with other systems. You can redirect one of your own URLs to wordpress.com, but if you want full control over everything from the code to the URLs used, you’re probably looking at a paid option. The free route may be a reasonable fi rst step for you, but here it is assumed that you’re going to want to perform surgery on your installation.

You’ll fi nd a starter list of for-fee hosting providers on www.wordpress.org, including the paid option on wordpress.com. Most have the latest, or close to latest, releases of the WordPress core

c01.indd 8 12/6/12 1:11 AM Getting Started ❘ 9

available as a package to be installed in conjunction with MySQL and a web server. The third hosting option is to install everything on servers that you own and operate. If your servers live in a hosting facility but you enjoy root administrative access, that’s equivalent to a do-it-yourself installation. WordPress requires a web server with PHP support, a URL rewriting facility, and an instance of MySQL. Apache is the most popular option for front-ending WordPress because it provides PHP interpretation through mod_php and URL rewriting in mod_rewrite. There is growing interest in lighttpd (Lighty) as a replacement for Apache, although the URL rewriting functionality needs a bit of hand-holding. Finally, you can use Microsoft’s IIS 7.0 as a web server with its URL_rewrite module. The emphasis on URL rewriting stems from WordPress’s support for “pretty” permalinks to blog entries, allowing you to create a URL tree organized by date, category, tag, or other metadata. Those mnemonic or human-readable URLs are converted into MySQL database queries to extract the right WordPress content based on titles or other keywords as part of the WordPress main loop, which is covered in detail in Chapter 5. Your web server decides whether the URL should be parsed by WordPress or if it refers to a specifi c HTML fi le based on what’s in the .htaccess fi le, and the URL rewriting rules assure that its contents are interpreted properly. Technically, URL rewriting isn’t required to install WordPress, but it’s good to have because it gives you tremendous fl exibility in the presentation and naming conventions used for your content’s URLs. Permalink design and practices are covered in more detail in Chapter 2, but keep the requirement in mind as you select your WordPress substrate. Up to this point, MySQL has been mentioned only in passing, but a brief review of MySQL requirements rounds out the hosting prerequisite list. It’s worth establishing some terminology and distinguishing between the MySQL software, database instances, and WordPress instances using MySQL. When you install and confi gure MySQL, you have a full-fl edged relational database system up and running. It doesn’t have to be confi gured on the same machine as your web server, and some hosting providers will create horizontally scalable MySQL “farms” in parallel to their web server front ends. An instance of MySQL running on a server can support multiple databases, each with a unique name. When you install WordPress, you’ll need to know the name of the MySQL database reserved for your content, although this information may be auto-generated and confi gured for you if you’re using a provider that supports WordPress and MySQL as an integrated package. WordPress creates a number of relational data tables in that named database for each website that you create. Confusion can result from nomenclature and complexity. You (or your hosting provider) may run multiple MySQL instances on multiple servers, and you’ll need to know where your database is hosted. Because each instance of MySQL can run multiple databases, and each database contains groups of tables, it’s possible to run multiple MySQL-based applications on the same hosting platform, using one MySQL instance or even one MySQL database. If you want to have multiple WordPress sites on the same server, you can share a single MySQL database instance for all of them provided you confi gure WordPress to distinguish the MySQL database table names within the MySQL database. It’s a simple confi guration option that is covered in the next section, and it highlights the distinction between multiple sets of tables in a database and multiple databases for distinct applications. Once you’ve secured the necessary foundation, it’s time to get the code up and running. Even if you’re using a hosting provider that installs MySQL and WordPress for you, it’s worth knowing how the server-side components interact in case you need to track down a problem when you’re deep in plugin development.

c01.indd 9 12/6/12 1:11 AM 10 ❘ CHAPTER 1 FIRST POST

Do It Yourself Installation The famous, fabled, fabulous fi ve-minute WordPress installation is a reality when everything is confi gured and coordinated properly. This section walks you through the steps that are often hidden from view when you use a provider with packaged installs, and highlights some of the common mis- fi res between WordPress and MySQL instances. The installation process is quite simple (assuming that your web server and MySQL server are already running): download the WordPress package and install it in your web server’s directory tree, and then navigate to your top-level URL and complete the confi guration. One (compound) sentence describes it completely. It’s possible and even advisable to install a fully functioning WordPress instance on your laptop or development machine, particularly if you are going to be working on the core, developing plugins or otherwise making changes that would create embarrassing failures during testing on a public website. Mac OS X comes with an Apache web server (with PHP and URL rewriting); download MySQL from www.mysql.com, or use a prepackaged confi guration such as MAMP (www.mamp.info, which includes the phpMyAdmin tool), and you’ll have a self-contained development and deployment lab. For other platforms, XAMPP (www.apachefriends.org) has a neatly integrated platform stack that runs on Windows, Mac OS and Linux foundations. Having everything under one hood is a powerful option for examining failure modes, as you’ll see in the next two sections. More information on working with WordPress locally is covered in Chapter 3.

Installing WordPress Files If you download the WordPress code from wordpress.org, you’ll get a zip (or tarball) archive that expands into a directory called wordpress. The fi rst part of a WordPress installation is to get the code into your web server’s directory structure; ensuring you have it in the right place is a critical step. Gloss over this part and you’ll fi nd your website ends up with a URL like http://example.com/ wordpress and you’ll either have to start over or e-mail ugly URLs to your friends and family. If that’s what you want — to distinguish your WordPress site from other content on your website or to isolate multiple sections — choosing the fi lesystem layout is equally important. Pick the top-level directory where you want to install WordPress. Most commonly, this is the root directory for your web server, and if you’re using a hosting provider it’s probably the subdirectory called public_html in the fi le tree. If you are using a packaged install where there’s a menu asking you for the target location, make sure you pick this top-level directory (and yes, you know that it already exists, that’s the point!); if you’re copying fi les from your local machine to the web server target using an FTP client, make sure you pick the right destination. The somewhat obvious move to copy the zip fi le to the server and then unpack it will put everything into a wordpress subdirectory, and if you want your WordPress site’s URL to be http://example.com rather than http://example .com/wordpress, move the fi les up one directory level before proceeding. There is a confi guration option to have your WordPress installation in a subdirectory to your top-level URL, so it’s not fatal if you drop WordPress into a less-than-desirable fi lesystem geography. That is covered at the end of this section. Once the WordPress fi les are installed, your fi lesystem browser should show you something like Figure 1-1, with an index.php and template wp-config-sample.php fi le. That’s the entirety of the WordPress system, which runs effectively within the web server’s PHP interpreter.

c01.indd 10 12/6/12 1:11 AM Getting Started ❘ 11

FIGURE 1-1: A clean but unconﬁ gured WordPress installation

At this point, if you’re doing a manual installation, you’ll want to create your own wp-config.php fi le by editing the sample provided and saving it in your top-level WordPress directory. As an alternative, you can navigate to your website’s URL, and the WordPress code will notice there’s no confi guration fi le and present you with dialog boxes like those in Figures 1-2 and 1-3 where you can fi ll in the details. You’ll need the MySQL database name, database username, and some idea of the WordPress database table prefi x (other than the default wp_). These lower-level details are the guts of the next section on database confi guration. If you are using a hosting provider with packaged installations, you probably won’t see this step because the WordPress fi les will be extracted and the MySQL database information will be automatically inserted into a confi guration fi le, no end user–serviceable parts inside.

FIGURE 1-2: WordPress will create a new wp-conﬁ g ﬁ le if one does not exist.

c01.indd 11 12/6/12 1:11 AM 12 ❘ CHAPTER 1 FIRST POST

FIGURE 1-3: Database conﬁ guration dialog box

What do you do if you already have HTML or other content at your target URL and you want to add WordPress to an existing site? Disposition of existing fi les depends on your desired fi rst user experience upon navigating to your URL. To use WordPress as a content management system as described here, your best choice is to save existing content and convert it into new posts or pages, effectively making your previous site color commentary and context for your WordPress-driven site. Alternatively, you can install WordPress in a subdirectory, keep your existing index.html fi le, and direct readers to your new content through a button or link on your extant home page. Don’t leave this to chance; if you have an index.html fi le and then install WordPress, you’ll have an index.php and an index.html fi le side by side and users will see one or the other depending upon the Directory Index confi guration of your site’s web server. Actions on existing content should be informed by how much traffi c that content is driving to your site: if your pages are responsible for search engine traffi c, you probably don’t want to disrupt the existing URLs that have been cached and should install WordPress in a subdirectory. If you feel strongly about making WordPress the wrapper around the user experience, move the content and include URL rewriting or redirection for pages that move into the WordPress world.

If you used a hosting provider’s packaged installation, or if you manually created a wp-config .php fi le and then navigated to your top-level URL, WordPress should have completed creating the database tables, created an administrative user for your WordPress, and set an initial password, as shown in Figure 1-4. Make sure you change the username to something different than admin.

c01.indd 12 12/6/12 1:11 AM Getting Started ❘ 13

FIGURE 1-4: Complete website details and set up admin user

Upon a successful installation, you should see a box like Figure 1-5 that indicates your fi ve minutes of famed installation are done.

FIGURE 1-5: Administrative information at the conclusion of a clean install

c01.indd 13 12/6/12 1:11 AM 14 ❘ CHAPTER 1 FIRST POST

The next section covers the MySQL-WordPress confi guration dance in more detail and is suitable reading even if thinking about SQL gives you hives. If you’re up and running, you can skip the next section and go right to the section, “Finishing Up.”

Database Conﬁ guration If your hosting provider spun up a MySQL database and created a user for you, check your resultant wp-config.php fi le to gather this information. It is necessary for the MySQL probing covered in this section, and it’s good to have in case you run into MySQL problems later on. There’s a username and password combination included in that fi le, so treat it the way you’d treat other login information. On the other hand, if you’re going deep on the do-it-yourself route, this section gives you a sense of what’s likely to create confusion or consternation as you pull the pieces together. In theory, MySQL setup for WordPress is trivial: make sure MySQL is up and running, create a WordPress user in MySQL, and then have that user create a database to hold the WordPress tables. You can use the MySQL command line or tools such as phpMyAdmin or Chive for these tasks, but bear in mind that MySQL has its own set of users and permissions granted to those users, distinct from those used by your (or your hosting provider’s) operating system. Once MySQL is installed, it will create a default table of users and grants, adding a root user on Unix systems that is a MySQL superuser, unrelated to the Unix root user. However, if you’re attempting to connect to your MySQL instance as the MySQL root user, those connections can only be made from localhost — the same machine on which MySQL is running. If you want to learn more about MySQL permissions, the table governing grants of those permissions to users, and how MySQL users are managed, refer to the “MySQL Reference Manual” (http://dev.mysql.com/doc/) and the sections on securing the initial MySQL accounts. No set naming conventions exist for WordPress users or databases; hosting providers will typically append the name of the package or your account information to distinguish users that benefi t from MySQL database co-tenancy. Again, it’s possible to have multiple databases, owned by the same user or different MySQL users, running in a single MySQL database server instance. In the example shown in Figure 1-3, wp_ is used as a prefi x for both usernames and database names, at least providing a hint to the database administrator that these belong to a WordPress installation. What can go wrong between WordPress and MySQL? The following are the three primary root causes of installation failure. Note that all of these conditions need to be fulfi lled at installation time; there has to be some basic database structure to contain the admin user before you can log in as that admin. 1. Web server can’t fi nd MySQL. Either you have the hostname for the MySQL server noted incorrectly in the wp-config.php fi le, or the web server is looking for a local MySQL instance and can’t open the socket connection to it. Here’s a simple example: when you run WordPress locally on Mac OS, MySQL creates the socket /tmp/mysql.sock for local connections, but the WordPress PHP code is going to look for /var/mysql/mysql.sock through the PHP engine’s MySQL module. Simply symbolically link one to the other: # ln -s /tmp/mysql.sock /var/mysql/mysql.sock

The actual fi lesystem path to the local MySQL socket is a function of the database confi guration; when it starts up, it creates the local socket. Where the PHP engine, and therefore any PHP- based applications, looks for this socket is PHP confi guration dependent. If you want to figure out exactly where the mismatch is, a bit of heavy-handed printf() style debugging helps.

c01.indd 14 12/6/12 1:11 AM Getting Started ❘ 15

Edit wp-includes/wp-db.php, the set of functions that establish WordPress’s database connection. If you’re seeing the “Error establishing a database connection” message during installation, insert an echo(mysql_error()); statement where the error is detected to see the details displayed along with the generic message, as shown in Figure 1-6: if (!$this->dbh) { echo(mysql_error()); $this->bail(sprintf(/*WP_I18N_DB_CONN_ERROR*/"

Error establishing a database connection

FIGURE 1-6: mysql_error( ) reporting a socket problem

The mysql_error() function is a PHP library function that spits out the error generated by the last MySQL function called. 2. WordPress fi nds MySQL but can’t log in. Most of the time, the MySQL username or password is wrong, particularly when you have to copy some arbitrary username generated by a hosting provider. Double-check your username data, and verify that it is refl ected properly in your wp-config.php fi le. You may also run into a password authentication issue when using MySQL 4.1 or MySQL 5.0 with some web servers’ PHP implementations; they only support the older MySQL 4.0 password hashing scheme. If this is the case, use MySQL’s OLD_PASSWORD() function to hash your WordPress user’s password in the backward-compatible format; the magic SQL incantation (at the MySQL command-line prompt or within the SQL window of MAMP) to address the following: SET PASSWORD FOR user@host = OLD_PASSWORD('password');

In this instance, user@host is your WordPress database username and database hostname, and password is the (clear text) password you provided in the confi guration fi le. 3. WordPress connects to MySQL but can’t select the database. Just because the web server can log in to the database server with your WordPress database user information doesn’t mean that there’s necessarily a database available to that user. This is another scenario best

c01.indd 15 12/6/12 1:11 AM 16 ❘ CHAPTER 1 FIRST POST

diagnosed with mysql_error(), by inserting it in wp-db.php where the selection error is identifi ed: function select($db) { if (!@mysql_select_db($db, $this->dbh)) { $this->ready = false; echo(mysql_error()); $this->bail(sprintf(/*WP_I18N_DB_SELECT_DB*/' ...

Can’t select database

If, after inserting the mysql_error() statement as described earlier, your attempts to complete installation result in an error box like that shown in Figure 1-7, your MySQL database wasn’t created under the appropriate database user, or the database user doesn’t have privileges to use it. Double-check what MySQL believes using the following command line: % /usr/local/mysql/bin/mysql -u wp_user1 -p Enter password: Welcome to the MySQL monitor. Commands end with; or \g. Your MySQL connection id is 174 Server version: 5.1.37 MySQL Community Server (GPL) mysql> show databases; +——————————+ | Database | +——————————+ | information_schema | | test | +——————————+ 2 rows in set (0.00 sec)

FIGURE 1-7: MySQL database selection error

Once you logged in as your designated MySQL database user, you didn’t see the MySQL database — in this case, it was probably created by MySQL user root, and permissions to access or modify it weren’t granted to the WordPress installation’s MySQL user. If you have

c01.indd 16 12/6/12 1:11 AM Finishing Up ❘ 17

MySQL root access, or suffi cient MySQL user privileges to create new databases within the MySQL instance, it’s easy enough to create a database once logged in on the command line:

mysql> create database wp_halstern; Query OK, 1 row affected (0.00 sec)

Again, it’s important to distinguish operating system users from MySQL users from WordPress users. MySQL users are defi ned in the database and granted privileges to create databases, muck with tables, and otherwise generate useful data. WordPress users exist within the WordPress database tables created during install; they only have privilege, context, and meaning once you’re logged in to WordPress. Once you have a clean WordPress installation, you should see a collection of tables named according to the table prefi x you set in wp-config.php; again, this is easy enough to verify using the MySQL command line: mysql> use wp_halstern; show tables; Database changed +—————————————+ | Tables_in_wp_halstern | +—————————————+ | wp_hs_comments | | wp_hs_links | | wp_hs_options | | wp_hs_postmeta | | wp_hs_posts | | wp_hs_term_relationships | | wp_hs_term_taxonomy | | wp_hs_terms | | wp_hs_usermeta | | wp_hs_users | +—————————————+ 10 rows in set (0.00 sec)

In this example, you set the database table prefi x to wp_hs_; if you later add another WordPress installation using the same database user and instance, you can simply set a different prefi x and have the two sites co-mingled in the same database table. You dig into the schema and uses of the ten basic WordPress database tables in Chapter 6. For now, once you are happily connected to MySQL, you’re ready for some fi nal clean-up and fi rst-time administration.

FINISHING UP

At this point, your MySQL database is up and running. There’s a home for your content, and your web server is happily executing the WordPress core code. There are just a couple more things to discuss.

First-Time Administration Once you have completed the installation, proceed to log in with the credentials you set up in Figure 1-4 and you’ll see the basic WordPress Dashboard captured in Figure 1-8.

c01.indd 17 12/6/12 1:11 AM 18 ❘ CHAPTER 1 FIRST POST

FIGURE 1-8: Dashboard view upon a ﬁ rst-time login

If you’re not redirected to the Dashboard through the Log In button, or if you happen to visit your website’s top-level URL fi rst, either click the Log In link on your website or explicitly go to the wp-admin subdirectory (example.com/wp-admin) to be presented with a login dialog box. Logging in to your website takes you to the WordPress Dashboard, which is both amazingly simple in its power and rich in its complexity and exposed features. What you do next with the Dashboard depends on how happy you are with the basic installation. If, as in the preceding example, you ended up with an older version of WordPress, click the Update button to do an in-place upgrade to the latest distribution. In addition to having a strong self-installation feature, WordPress includes self-update functions (in wp-admin/includes/update .php if you’re looking for them). You may decide to change some basic confi guration options, such as the database name or the MySQL database user, although you’ll only change the default of root@localhost if you have full control over the web and database servers. The confi guration fi le also has entries for “security keys” that are used to provide stronger security for browser cookies. Security keys are discussed in more detail in Chapter 11. Editing your wp-config.php fi le affects the changes right away. Changing the database table prefi x, for example, causes WordPress to instantiate a new set of tables and create a clean-slate installation. Make those edits and then go back to your top-level URL and you’ll fi nd yourself with new admin user information and logged in to a starter Dashboard, as in Figure 1-8. Old tables aren’t removed from MySQL, so you’ll have to do manual cleanup. At this point, if you want to set your URL to be different from the location in which you installed WordPress, you can choose Settings and General from the Dashboard and change the URLs for

c01.indd 18 12/6/12 1:11 AM Finishing Up ❘ 19

both your top-level address as well as the WordPress installation directory. If you dissociate your site’s URL and the WordPress directory, make sure you move the index.php fi le to the desired top-level URL, and then edit the last line to include the proper subdirectory path to WordPress. Before creating your fi rst post, it’s also a good idea to establish a permalink structure so that everything you write follows the naming conventions you’ve chosen to make it relatively easy for readers to fi nd, share, and link to your content. As expected, it’s another option in the Settings portion of the Dashboard; options for permalink naming and their impact on performance and database schema are covered in more detail in the next chapter. Whether it’s really been fi ve minutes, or a few hours of tracking down mismatches in hostnames, usernames, and database confi gurations, you’re now ready to publish the fi rst post of your own writing.

First Post A successful WordPress installation already has a fi rst post and comment published, thus assuring that all of the moving pieces are moving in unison, and giving your website some initial content. When you’re ready to add your own fi rst words, either use the right-hand QuickPress panel in the Dashboard to post an entry (you may need to dismiss the new website help fi rst), or go to Posts and click Add New to be taken to the built-in WordPress editor. Figure 1-9 shows an entry in progress in the QuickPress panel, followed by the updated Dashboard after it’s been successfully posted.

FIGURE 1-9: Publishing from the QuickPress panel

c01.indd 19 12/6/12 1:11 AM 20 ❘ CHAPTER 1 FIRST POST

If your tastes run more old-school, you can always crank out content in your favorite text editor and then copy it into the editing pane. Be careful with WYSYIWIG word processors such as Microsoft Word or OpenOffi ce if you want to copy into the WordPress HTML composition window because the HTML will be riddled with additional tag and style information. Finally, a variety of standalone editors, such as Illumnix’s Ecto, publish to WordPress using the Atom Publishing Protocol or XML-RPC. Options for enabling posts to be published remotely are, as you’d expect, in the Dashboard’s Settings section under Writing options. Click Publish for your own “Hello World” moment. Multiple subsystems created that editing pane, saved the content in a database, generated and saved the referential metadata, and then emitted nice-looking HTML. Most of the user-visible pieces are governed through the Dashboard and certain functions will be covered in various chapters.

SUMMARY

This chapter covered how WordPress got to where it is today, with a brief history lesson and also touching on its current popularity. Part of WordPress’s rise in the web realm is attributed to the simplicity of the installation process. The next chapter dives into the core of WordPress so that you can take advantage of its extensibility, friendly design, and function.

c01.indd 20 12/6/12 1:11 AM 2 Code Overview

WHAT’S IN THIS CHAPTER?

➤ Downloading WordPress ➤ Conﬁ guring wp-config.php and .htaccess ➤ Exploring the wp-content directories ➤ Enabling maintenance mode in WordPress

WordPress is a software package that comprises groups of source code fi les that perform specifi c tasks within the system. Understanding the code, including fi le and folder structure, is essential to understanding how WordPress works as a whole. After reading this chapter, you will be familiar with downloading and exploring the WordPress fi lesystem. This chapter also discusses confi guring key WordPress fi les, including the powerful wp-config.php and .htaccess fi les. It also covers some advanced confi guration options available in WordPress.

DOWNLOADING

The fi rst step to installing WordPress on your own hosting account is to download the source fi les required for WordPress to run. This section digs deeper into the core of WordPress.

Download Locations You can download the latest stable release of WordPress directly from WordPress.org by visiting the download page located at http://wordpress.org/download/.

c02.indd 21 12/6/12 1:12 AM 22 ❘ CHAPTER 2 CODE OVERVIEW

You can also update WordPress directly from your current WordPress installation by visiting the Updates WordPress section under the Dashboard ➪ Updates SubPanel. Click the Download button to download the latest version of WordPress to your computer. WordPress also features Subversion (SVN) access. Subversion is a free, open source version control system. WordPress uses Subversion to manage fi les and directories and the changes made to them. You can download the latest WordPress source code by checking out http://core.svn .wordpress.org/trunk/. The SVN trunk directory contains the bleeding edge version of WordPress that is actively being developed. Typically, this version of WordPress contains bugs and is generally used for testing purposes. Running a production website using the trunk version of WordPress is not recommended. SVN is the mechanism developers use to actively develop on the WordPress core software. With SVN, you can create and submit patch fi les for inclusion into the WordPress core. Chapter 16 covers this in detail.

Available Formats The default format for the WordPress software download is in a compressed zip archive named latest.zip. You can also download WordPress in a compressed tar archive named latest.tar.gz. There is no difference between the fi les in the archive, only the compression method used. You can download the zip and tar archives directly from these URLs:

➤ http://wordpress.org/latest.zip

➤ http://wordpress.org/latest.tar.gz

These download links never change. Each new version of WordPress is automatically compressed and saved at this location when the version is tagged. When you save the archive to your computer, you should rename the fi le to include the WordPress version number, such as wordpress-3.5.zip. This will help you remember what version of WordPress you saved to your computer.

Release Archive WordPress.org features a Release Archive for WordPress. The Release Archive features a list of downloadable archives for every release of WordPress since version 0.71. The archive is located at http://wordpress.org/download/release-archive/. Remember that only the most current version of WordPress is actively maintained so these downloads are more for reference than actual use. “Actively maintained” means that critical fi xes for security, performance, or reliability problems are made to the active branch and not applied retroactively to previous releases. If you need the fi x, you’ll need to upgrade your installed version of WordPress. Another great use for these older versions of WordPress is to roll a website back to a previous version. For example, if you update a very old version of WordPress to the latest stable version and run into problems, you could easily download the old version that the website was originally running to revert to. The Release Archive also features a download for every beta and release candidate version of WordPress as well. This is great to see the overall growth of WordPress as a software platform.

c02.indd 22 12/6/12 1:12 AM Directory and File Structure ❘ 23

The release archives are also useful if you need to update an old version of WordPress that has hacks made to the core. Simply compare the website’s WordPress source code with the same version of WordPress from the release archive and any differences, or core hacks, will be discovered.

DIRECTORY AND FILE STRUCTURE

The WordPress source code features many different PHP, JavaScript, and CSS code fi les. Each fi le serves a specifi c purpose in WordPress. The beauty of open source software is that all code is publicly available, which means you can easily explore the code to better understand how WordPress functions. The best resource for learning WordPress is the WordPress software itself. After extracting the WordPress download, you will notice the set fi le structure for WordPress, as shown in Figure 2-1. WordPress comes with three directories by default: wp-admin, wp-content, and wp-includes. Core fi les are all fi les in the wp-admin and wp-includes directories and the majority of the fi les in the root WordPress directory. The wp-content directory holds all of your custom fi les, including themes, plugins, and media. This directory contains the code that controls content manipulation and presentation in WordPress. WordPress HTML content, such as pages and posts, is stored in the MySQL database along with metadata such as tag and category structures, both of which are covered in detail in Chapter 6. FIGURE 2-1: Default WordPress ﬁ le and folder Modifying any of the core WordPress fi les can structure result in an unstable website. An innocuous but badly executed change to the Dashboard or login functions, for example, will leave you with a WordPress installation that can’t be managed. Core changes also make it very diffi cult to update WordPress because all changes made are overwritten when the updated version of WordPress is installed. As discussed in the previous section, critical fi xes to the WordPress core are only made in the current branch, so if you are forced to update WordPress to pick up a security fi x, you’re going to have to re-integrate any core changes you’ve made and hope they don’t confl ict with the changes you want. Maintaining the integrity and stability of your WordPress installation over time is much simpler when you’re not changing fi les in the core.

In general, the wp-admin, wp-includes, and root directory core WordPress fi les should never be edited, but the next section covers some core root directory fi les that can be modifi ed as part of advanced confi guration. In general, however, follow this rule that is revisited in Chapter 4: Don’t hack the core!

c02.indd 23 12/6/12 1:12 AM 24 ❘ CHAPTER 2 CODE OVERVIEW

WORDPRESS CONFIGURATION

WordPress features specifi c fi les that can be edited for different purposes. These fi les can alter how WordPress functions. Always test changes in a development environment before publishing to a production server. This section covers database connections, storing FTP info, enabling debugging tools, and more using wp-config.php. It also covers the power of the .htaccess fi le, including increasing PHP memory limits and max upload sizes, creating redirects, and setting access restrictions.

wp-conﬁ g.php File The most important fi le in any WordPress installation is the wp-config.php fi le. This fi le contains all database connection settings, including the database name, username, and password to access your MySQL database. This fi le also stores additional database and other advanced settings. The wp-config.php fi le was originally named wp-config-sample.php. Renaming the fi le to wp-config.php is one of the fi rst steps to installing WordPress.

The wp-config fi le is typically stored in the root directory of WordPress. Alternatively, you can move the wp-config fi le out of the WordPress root directory and into the parent directory. So if your WordPress directory is located here,

/public_html/my_website/wp-config.php

you can safely move the fi le to here:

/public_html/wp-config.php

WordPress looks for the wp-config fi le in the root directory fi rst, and if it can’t fi nd that fi le it looks in the parent directory. This happens automatically so no settings need to be changed for this to work.

NOTE Moving the wp-config.php out of the root WordPress directory is a good security measure, making it nearly impossible to potentially access this fi le from a web browser.

Some options in WordPress are stored as constants and these can be seen in the wp-config.php fi le. The constraints all have the same format:

define( 'OPTION_NAME', 'value' );

OPTION_NAME is the name of the option constant being set; value is the option value and can be updated to whatever setting you would like to save for that option. When adding new options to the wp-config.php fi le, it’s important the options are added above the line that reads:

/* That's all, stop editing! Happy blogging. */

c02.indd 24 12/6/12 1:12 AM WordPress Conﬁ guration ❘ 25

If your WordPress installation is having problems connecting to your database, this is the fi rst place to start troubleshooting. If you receive the error message “Error establishing a database connection,” the fi rst thing to do is verify that the DB_NAME, DB_USER, and DB_PASSWORD options are correctly set for your database server. Also verify that the DB_HOST name is set to the correct host for your server. Typically, this is set to localhost, but some hosting companies confi gure WordPress packages with web servers and MySQL servers on different machines, necessitating a host company–specifi c confi guration option to locate the MySQL database. Contact your hosting tech support or consult their online documentation for the correct host value to set here.

You can change the database character set (charset) by changing the DB_CHARSET option value. By default, this is set to utf8 (Unicode UTF-8), which supports any language, and is almost always the best option.

Since WordPress 2.2, the DB_COLLATE option has allowed designation of the database collation, that is, sort order of the character set. (A character set is a collection of symbols that represents words in a language. The collation determines the order to use when sorting the character set, usually alphabetical order.) This option, by default, is blank and should typically stay that way. If you would like to change the database collation, just add the appropriate value for your language. You should change this option before installing WordPress. Altering this value after installation could cause problems in WordPress.

WordPress security can be strengthened by setting secret keys in your wp-config.php fi le. A secret key is a hashing salt, which makes your site harder to hack by adding random elements (the salt) to the password you set. These keys aren’t required for WordPress to function, but they add an extra layer of security on your website. To have secret keys auto-generated for you, visit the link to WordPress.org for secret key generation in your wp-config.php fi le (https://api.wordpress.org/secret-key/1.1/salt/), shown in Figure 2-2. Alternatively you can just type a bunch of random characters in place of “put your unique phrase here.” The goal is to use secret keys that are 100 percent random and unique.

FIGURE 2-2: Randomly generated secret keys

You can add or change these keys at any time; the only thing that will happen is all current WordPress cookies will be invalidated and your users will be required to log in again.

Another security feature included in wp-config.php is the ability to defi ne the database table prefi x for WordPress. By default this option value is set to wp_. You can change this value by setting the $table_prefix variable value to any prefi x, like so:

$table_prefix = 'bwar_';

c02.indd 25 12/6/12 1:12 AM 26 ❘ CHAPTER 2 CODE OVERVIEW

If a hacker is able to exploit your website using an SQL injection attack, this will make it harder for them to guess your table names and quite possibly keep them from doing SQL injection at all. Setting the table prefi x to a unique value also makes it possible to run multiple WordPress installations in a single database. If you want to change the table prefi x after you have installed WordPress, you can use the WP Security Scan plugin (http://wordpress.org/extend/plugins/wp-security-scan/) to do so. Make sure you make a good backup before doing this, however.

The wp-config fi le also contains the option for localizing your installation of WordPress. WordPress has the built-in capability to be used in many different languages. Setting the WPLANG option value sets the default language for WordPress to use. A corresponding MO (machine object) fi le for the selected language must be installed to wp-content/languages for this option to work. MO fi les are compressed PO (portable object) fi les, which contain translations for WordPress messages and text strings in a specifi c language. The MO and PO fi les are components of the GNU “gettext” subsystem that underlies the WordPress multilanguage capabilities. For a full list of available MO language fi les, visit the following resources:

➤ WordPress in Your Language Codex page — http://codex.wordpress.org/ WordPress_in_Your_Language

➤ WordPress Language File Repository — http://svn.automattic.com/wordpress-i18n/

Debugging errors in WordPress can be made easier using the WP_DEBUG option. Enabling WP_DEBUG displays WordPress errors on the screen, rather than suppressing those errors with a white screen. To enable WP_DEBUG, just set the option value to true:

define( 'WP_DEBUG', true );

New installations of WordPress will have this option defi ned in wp-config as false. If this option is not defi ned, it defaults to false and error messages are not displayed. Remember to disable or remove this option when you are done debugging because error messages might help hackers fi nd vulnerabilities in your website. It’s best to always keep WP_DEBUG enabled when developing in WordPress to address any warnings or errors that might be displayed.

Advanced wp-conﬁ g Options You can set additional advanced options in your wp-config fi le. These options are not in the wp-config fi le by default so you will need to manually add them to the fi le. To set your WordPress address and blog address, use the following two options:

define( 'WP_SITEURL', 'http://example.com/wordpress' ); define( 'WP_HOME', 'http://example.com/wordpress' );

The WP_SITEURL option allows you to temporarily change the WordPress site URL. This does not alter the database option value for siteurl, but instead temporarily changes the value. If this option is removed, WordPress reverts back to using the siteurl database setting. The WP_HOME option works the exact same way, letting you temporarily change the home value for WordPress. Both values should include the full URL including http://.

c02.indd 26 12/6/12 1:12 AM WordPress Conﬁ guration ❘ 27

NOTE This is a useful technique if you are building a WordPress website under a temporary development URL, such as new.example.com. You can simply remove these two options when you go live and WordPress will load using the production URL instead.

Version 2.6 introduced an option that allows you to move the wp-content directory. The two required options are:

define( 'WP_CONTENT_DIR', $_SERVER['DOCUMENT_ROOT'] . '/wordpress/blog/wp-content' ); define( 'WP_CONTENT_URL', 'http://domain.com/wordpress/blog/wp-content');

The WP_CONTENT_DIR option value is the full local path to your wp-content directory. The WP_CONTENT_URL is the full URI of this directory. Optionally, you can set the path to your plugins directory like so:

define( 'WP_PLUGIN_DIR', $_SERVER['DOCUMENT_ROOT'] . '/blog/wp-content/plugins' ); define( 'WP_PLUGIN_URL', 'http://example/blog/wp-content/plugins');

WP_PLUGIN_DIR and WP_PLUGIN_URL are options used by plugin developers to determine where your plugin folder resides. If a plugin developer is not using these constants, there is a very good chance their plugin will break if you move your wp-content directory. Never move the wp-content directory on your production server without fi rst testing in a development environment. WordPress saves post revisions for each saved edit made to a post or page. Edits are saved by clicking either the Save or Publish button, and also by the built-in auto-save feature of WordPress. Imagine if each post you create has 10 revisions. If you had 100 posts, that would be 1,000 records in your database. This can quickly increase the size of your database and may even slow down your website because table records can take longer to fetch in larger databases. Luckily, WordPress has a built-in post revisions option called WP_POST_REVISIONS. You can set this option to false to completely disable post revisions altogether, or you can specify a maximum number of revisions to keep for each post or page. Following are examples of both scenarios:

define( 'WP_POST_REVISIONS', false ); define( 'WP_POST_REVISIONS', 5 );

You can also confi gure the auto-save interval by setting the AUTOSAVE_INTERVAL option. WordPress uses AJAX when editing a post to auto-save revisions. By default, this interval is 60 seconds. You can set the interval in seconds for auto-save in wp-config. Set auto-save to 5 minutes by using this code:

define( 'AUTOSAVE_INTERVAL', 300 );

A great debugging option is SAVEQUERIES. Activating this option saves all database queries into a global array that can be displayed on your page. This can help you debug query issues, and also to

c02.indd 27 12/6/12 1:12 AM 28 ❘ CHAPTER 2 CODE OVERVIEW

see exactly what WordPress is executing on each page load. If you are working on a theme or plugin, and can’t seem to get the right set of posts back, this debug option will show you exactly what WordPress is asking for out of the database. Enable this option by setting the value to true:

define( 'SAVEQUERIES', true );

To display the query array in your theme, add the following code to any theme template fi le to view:

if ( current_user_can( 'manage_options' ) ) { global $wpdb; print_r( $wpdb->queries ); }

The preceding code displays the saved query array only if the logged-in user has the ability to manage options, essentially locking it down so only site administrators will see the output. Themes and template fi les are covered in Chapter 9, “Theme Development.”

You can also enable logging directly from your wp-config fi le. To enable logging, fi rst you need to create a php_error.log fi le and upload it to your root WordPress directory. Then simply turn on the log_errors PHP option and point to your logging fi le:

@ini_set( 'log_errors','On' ); @ini_set( 'display_errors','Off' ); @ini_set( 'error_log','/public_html/wordpress/php_error.log' );

All errors will now be logged to this fi le. This will also log any errors produced by enabling the WP_DEBUG option discussed earlier. In the preceding example display_errors is set to Off, which is perfect for a production website because you don’t want error messages displayed. If you are debugging and want to view errors in real time, just set that option to On. Remember the error_log value is relative to the web server’s document root, not the WordPress root.

You can also set the memory limit WordPress is allowed to use with the WP_MEMORY_LIMIT option. If your website hits the memory limit set for WordPress to run, you will see the error “Allowed memory size of xxxxx bytes exhausted.” Increasing the memory limit fi xes this problem. The memory limit is set by defi ning the megabytes needed:

define( 'WP_MEMORY_LIMIT', '32M' );

Setting this option works only if your hosting company allows it. Some hosting companies will not allow you to dynamically change the memory limit and will have this value set very low. This problem is usually found on lower-cost hosting companies that maintain their price points by packing more web server instances onto a single physical host, creating contention for memory footprint. This increases the memory only for WordPress and not other applications running on your server. To increase the memory limit across all of your websites, set the php_value memory_limit variable in your php.ini fi le. For example, when importing large amounts of content, say months or years worth of blog posts, it’s likely you’ll hit this memory limit.

c02.indd 28 12/6/12 1:12 AM WordPress Conﬁ guration ❘ 29

One amazing feature of WordPress is the built-in localizer. WordPress displays in English by default, but can easily be set to display any language that has been translated. Setting the WPLANG option triggers WordPress to load the specifi ed language fi les:

define ( 'WPLANG', 'en-GB' );

The option value shown previously comprises the ISO-639 language code followed by the ISO-3166 country code. So en-GB would be English-Great Britain. This setting will reference your .mo and .po fi les for language translation.

You can also defi ne the LANGDIR option. This option defi nes what directory will hold your language .mo fi les. By default, WordPress looks in wp-content/languages for the .mo fi le. If you would like to move this folder, just set the LANGDIR option like so:

define( 'LANGDIR', '/wp-content/bury/my/languages' );

WordPress will now look in the new location for your .mo fi les.

CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE are also very powerful options. They are useful if you want to have two or more individual WordPress installs use the same user accounts. Remember to set this prior to installing WordPress.

define( 'CUSTOM_USER_TABLE', 'joined_users' ); define( 'CUSTOM_USER_META_TABLE', 'joined_usermeta' );

Setting these two options enables you to defi ne the name of the default WordPress user and user meta table. Doing this means both websites share user information including usernames, passwords, author bios, and so on. This is a great way to set up a new installation of WordPress but not lose sync with your current user base. If you would like your users to have different roles on each WordPress install, but still share user accounts, don’t set the CUSTOM_USER_META_TABLE option. Everything stored in the user tables will stay the same, but everything else will be blog-specifi c (that is, user level, fi rst and last name, and so on).

You can set multiple cookie options such as COOKIE_DOMAIN, COOKIEPATH, and SITECOOKIEPATH. These options are typically used in a WordPress Multisite installation utilizing subdomains for websites. This allows you to set the primary domain so cookies can be created and validated on all subdomains in the network.

define( 'COOKIE_DOMAIN', '.domain.com' ); define( 'COOKIEPATH', '/' ); define( 'SITECOOKIEPATH', '/' );

Typically, you won’t need to use or change this option, but if you run into issues with cookies, this is the fi rst place to check. Since the inclusion of the automatic installer functionality for plugins and themes, as well as the automatic update process, you can set FTP settings directly in your wp-config fi le. This is only needed if your host is not confi gured to support the automatic install process. This is easily detect- able because each time you try to install a plugin or theme you are asked for your FTP information.

c02.indd 29 12/6/12 1:12 AM 30 ❘ CHAPTER 2 CODE OVERVIEW

To save your FTP information in WordPress, add the following options in your wp-config fi le:

define( 'FTP_USER', 'username' ); define( 'FTP_PASS', 'password' ); define( 'FTP_HOST', 'ftp.example.com:21' );

Just enter your FTP username, password, and host with port and you’re all set! WordPress will no longer ask for your FTP information when using the automatic installer. You can set additional FTP/SSH options for various confi gurations:

// sets the filesystem method: "direct", "ssh", "ftpext", or "ftpsockets" define( 'FS_METHOD', 'ftpext' ); // absolute path to root installation directory define( 'FTP_BASE', '/public_html/wordpress/' ); // absolute path to wp-content directory define( 'FTP_CONTENT_DIR', '/public_html/wordpress/wp-content/' ); // absolute path to wp-plugins directory define( 'FTP_PLUGIN_DIR ', '/ public_html /wordpress/wp-content/plugins/' ); // absolute path to your SSH public key define( 'FTP_PUBKEY', '/home/username/.ssh/id_rsa.pub' ); // absolute path to your SSH private key define( 'FTP_PRIVKEY', '/home/username/.ssh/id_rsa' ); // secure FTP SSL-connection if supported by the hosting company define( 'FTP_SSL', false );

You can also override default fi le permissions in WordPress using the FS_CHMOD_FILE and FS_CHMOD_DIR options:

define( 'FS_CHMOD_FILE',0644 ); define( 'FS_CHMOD_DIR',0755 );

The numeric single digit values represent the User, Group, and World permissions set for fi les and folders on your web server. To learn more about WordPress and fi le permissions visit http://codex.wordpress.org/Changing_File_Permissions. These settings can help with certain hosting companies that use restrictive permissions for all user fi les. This will override the server settings and should allow WordPress updates and auto installations to work.

The WP_CACHE option is required for some caching plugins to work. Enabling this option will include the fi le wp-content/advanced-cache.php. To enable this option use the following code:

define( 'WP_CACHE', true );

WordPress has numerous constant options that you can set. There is a PHP function to view all constants currently set on your installation:

print_r( @get_defined_constants() );

An advanced option is forcing SSL on login to your WordPress site. This requires users to log in via the HTTPS access link and encrypts all data being transferred to and from your website. To activate SSL on login, add the FORCE_SSL_LOGIN option like so:

c02.indd 30 12/6/12 1:12 AM WordPress Conﬁ guration ❘ 31

define( 'FORCE_SSL_LOGIN', true );

You can also force all admin pages to use SSL. This is activated with the FORCE_SSL_ADMIN option, like so:

define( 'FORCE_SSL_ADMIN', true );

This forces all admin dashboard pages (/wp-admin) to be encrypted with SSL. Keep in mind that activating this setting slows down your admin page load times, but all data passed to and from WordPress will be encrypted using SSL. Also remember that your website must be confi gured to work with SSL. The quick way to test is to visit your site using https, as in https://example.com. If the page loads, SSL is set up on your server. Forcing SSL on the admin side of WordPress is a great security enhancement. All data passed to and from WordPress will be encrypted, preventing someone from potentially stealing your WordPress login credentials. Since version 2.9, WordPress has featured a trash bin. This trash bin contains any posts, pages, attachments, and comments that have been deleted. This allows you to recover any content that you might have accidently deleted in WordPress. By default, the trash bin is emptied every 30 days. Emptying the trash bin will permanent delete any items in the trash. You can modify this interval by setting the EMPTY_TRASH_DAYS option like so:

define( 'EMPTY_TRASH_DAYS', 7 );

The trash will now automatically be emptied every 7 days. You can also disable the trash completely by setting the option value to 0. The trash link will now be replaced with a Delete Permanently link. Keep in mind that WordPress will not ask for a confi rmation when you click Delete Permanently. There is also an option to disable WordPress cron. Cron is used to execute scheduled tasks in WordPress. Some common schedule tasks include posting a scheduled post and checking for new versions of WordPress, themes, and plugins. To disable WordPress cron add this option to your wp-config fi le:

define( 'DISABLE_WP_CRON', true );

This section covered a lot of common options for wp-config. There are many more, less common, options for wp-config available in WordPress. A great resource for learning about wp-config options is the Codex: http://codex.wordpress.org/Editing_wp-config.php.

.htaccess The .htaccess fi le is used primarily for creating pretty permalinks and keyword injected URLs for your website. WordPress by default creates ugly query-string formed URLs, usually with an ID present, such as http://example.com/?p=45. These URLs are completely functional but aren’t very friendly to search engines and site visitors. By enabling pretty permalinks, WordPress creates URLs based on site content, such as post and page titles, category and tag names, and dates for archives.

c02.indd 31 12/6/12 1:12 AM 32 ❘ CHAPTER 2 CODE OVERVIEW

Enabling Permalinks To enable permalinks visit the Settings ➪ Permalinks SubPanel on your WordPress Dashboard, as shown in Figure 2-3. Select any permalink structure other than Default and click the Save Changes link.

Upon saving your changes, WordPress tries to create your default .htaccess fi le. If your root WordPress directory is writable by the server, the fi le is created automatically. If WordPress is unable to create the .htaccess fi le, you will see instructions on how to manually create the file, as shown in Figure 2-4.

FIGURE 2-4: Manual info for FIGURE 2-3: Enabling permalinks in WordPress creating the .htaccess ﬁ le

Setting a permalink structure using the month and year like this,

/%year%/%monthnum%/%postname%/

creates a permalink like this:

http://example.com/2012/10/halloween-party/

Using permalinks offers many advantages, such as: ➤ Search Engine Optimization (SEO) — Keywords in your URL can give your website a big SEO boost. Search engines will use these keywords in their algorithm for positioning in their search results. ➤ Forward compatibility — Regardless of what platform your website uses (WordPress, Drupal, Joomla!), having a solid permalink structure can be easily replicated should you ever migrate. ➤ Usability — Visitor-unfriendly ID URLs make it equally unpleasant to share a link with a friend. It’s diffi cult to differentiate the content between your ID-driven URLs.

c02.indd 32 12/6/12 1:12 AM WordPress Conﬁ guration ❘ 33

➤ Sharing — In this Internet era of social networking, sharing is a natural extension of your online presence. Keywords in the URL would make fi nding your link extremely easy and convey an immediate context for the content.

.htaccess Rewriting Rules Usually a web server takes a URL that references a fi le in the server’s document fi lesystem, loads that fi le, and processes the content in it to generate HTML sent back to the user’s browser. For WordPress fi les such as wp-login.php, that’s exactly how the login screen is generated. When presented with a pretty permalink such as example.com/2012/travel/haddonfield, the web server just needs to load the main loop of WordPress so that the core code can parse the URL and turn it into a database query that fi nds a post with the title Haddonfi eld in the category Travel. Unlike a static website where you would have created a fi le with that name, WordPress stores its content in a database — only a few fi les are loaded directly. The “secret sauce” behind the WordPress permalink mechanism is summarized in three rewriting rules added to the .htaccess fi le when you enable permalinks:

RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . /index.php [ L]

Quite simply, these rules check the URL used to access your site to see if it refers to an existing fi le or directory in the fi lesystem hierarchy. The !-f and !-d notations are negations; .htaccess is ensuring that the URL does not refer to any valid fi le or directory pathname. If the URL does, in fact, match a valid fi le — for example, a WordPress administrative function such as wp-login .php — then no rewriting is done and the web server tries loading that fi le (to execute the PHP code contained within). If there’s no fi le or directory at the path specifi ed by the supplied URL, then the incoming URL is rewritten to index.php, invoking the core of the WordPress system. You’ll dig into the steps used to convert a URL string into a MySQL query in a bit more detail as a preface to the discussion of the content display loop in Chapter 5.

NOTE The simple check for whether a fi le or directory exists can have unintended side effects if you put non-WordPress web server content in the same directory structure as the WordPress code. For example, consider a directory of images as a peer directory of wp-content: example.com/wp-content and example.com/images. You might choose to bypass the WordPress media library because those images are managed by their own set of ingest processes. What happens when a user forms a URL with a mistyped image name that points to a nonexistent fi le? The .htaccess rewriting rule will fi re because there is no fi le with that name, and the WordPress core will be started. A user expecting to see an image will instead get the default WordPress site content when they should have received a 404 error for a nonexistent URL target. If you are going to add directories around your WordPress installation, either place WordPress in its

continues

c02.indd 33 12/6/12 1:12 AM 34 ❘ CHAPTER 2 CODE OVERVIEW

(continued) own subdirectory (example.com/wordpress) or add a rewrite rule to .htaccess that recognizes your added peer directories and immediately hands those URLs off to the web server:

RewriteRule ^images/(.*) images/$1 [L]

This rule effectively says, “Take any URL that starts with the component images, and pass it off to the web server.” The [L] directive means “stop processing after matching this rule,” and the rewrite itself simply echoes back what it was passed. If you’re going to have a few directories sitting in parallel with the WordPress installation, you’ll need one rewrite rule for each.

The .htaccess fi le can also manage URL redirects. If you change your About page from http:// example.com/about to http://example.com/about-me, anyone who visits your original URL will hit a 404 page. A URL redirect will redirect from the old URL to the new URL so your visitors won’t get lost. This also alerts search engines about the new URL so they can update their index. Following is an example of a 301 permanent redirect to a static page:

redirect 301 /about http://example.com/about-me

WordPress does some additional rewriting and cleanup of URLs to improve search engine results, as you’ll see in Chapter 5.

Conﬁ guration Control Through .htaccess The .htaccess fi le is very powerful and can control more than just URL structure. For instance, you can control PHP confi guration options using the .htaccess fi le. To increase the memory allotted to PHP use this command:

php_value memory_limit 64M

This increases the memory limit in PHP to 64 MB. You can also increase the max fi le size upload and post size:

php_value upload_max_filesize 20M php_value post_max_size 20M

Now the maximum fi le size you can post from a form and upload is set to 20 MB. Most hosting companies set these values to around 2 MB by default so these are settings that will be used often for larger fi le uploads. Not all hosting companies will allow these values to be set in your .htaccess fi le, and they could create an error on your website if that is the case.

c02.indd 34 12/6/12 1:12 AM WordPress Conﬁ guration ❘ 35

The .htaccess fi le can also be used for security purposes. Using .htaccess allows you to restrict access to your website by IP address, essentially locking it down from anonymous visitors. To lock down your website by IP addresses, add the following code to your .htaccess fi le:

AuthUserFile /dev/null AuthGroupFile /dev/null AuthName "Access Control" AuthType Basic order deny,allow deny from all #IP address to whitelist allow from xxx.xxx.xxx.xxx

Replace xxx.xxx.xxx.xxx with any IP address that you want to grant access to your website. You can have multiple allow from lines so add as many IP addresses as you need. This allows access to your website only if you are using an IP address defi ned here.

A more widely used option is to lock down your wp-admin directory. This means that only IP addresses you specify can access your admin dashboard URLs. This makes it much harder for anyone else to try to hack your WordPress back end. To accomplish this, create a separate .htaccess fi le in your wp-admin directory with the preceding code. Remember that most ISPs assign client addresses dynamically so the IP address of the computer you are using will change on occasion. If you get locked out, just update your .htaccess fi le with your new IP address or delete the fi le altogether. This is not a good tip if you allow open registrations on your website because you need to allow your users access to the wp-admin directory.

You can also allow wildcard IP addresses. For example, 123.123.123.* would allow access to anyone who matches the fi rst three IP address octets, with the fi nal digit being a wildcard. You can also allow a range of IP address. For example 123.123.123.110-230 would allow anyone with an IP address between 123.123.123.110 and 123.123.123.230.

You can also enable error logging from the .htaccess fi le. The fi rst step is to create a php-errors .log fi le in your WordPress root directory. Then add the following code to your .htaccess fi le to enable error logging:

php_flag display_startup_errors off php_flag display_errors off php_flag html_errors off php_flag log_errors on php_value error_log /public_html/php-errors.log

This enables error logging but suppresses any error messages from displaying. Again this is a perfect setup for a production environment because you don’t want errors publicly displayed.

The .maintenance File WordPress has a built-in maintenance mode that can be enabled by the .maintenance fi le. The.maintenance fi le is used by WordPress during the auto-update process. This prevents visitors

c02.indd 35 12/6/12 1:12 AM 36 ❘ CHAPTER 2 CODE OVERVIEW

from seeing any error messages as WordPress core fi les are updated. To test this feature, simply create a new .maintenance fi le and add the following line of code:

Add this fi le to your WordPress root directory and your website will instantly enter maintenance mode. This locks down your website for all visitors and displays a generic maintenance message “Briefl y unavailable for scheduled maintenance. Check back in a minute.” The time() function can be replaced with any UNIX-formatted timestamp.

You can set a custom maintenance page by creating a maintenance.php fi le and placing it in your wp-content directory. WordPress uses this fi le to display during any forced maintenance periods that you set. This allows you to create a custom maintenance notice to your website visitors.

This fi le is also used by the WordPress automatic update process. A .maintenance fi le is created right before WordPress installs the new core fi les during an update. This ensures there are never any error messages for your visitors during this process.

WP-CONTENT USER PLAYGROUND

The wp-content directory stores just about every fi le for customizing WordPress. This directory stores your plugins, themes, and additional fi les to extend WordPress in any way imaginable.

The wp-content directory has a single PHP fi le, index.php. The contents of this fi le are shown here:

So what’s the point of this fi le? Actually this is a very important file. The index.php fi le blocks anyone from viewing a directory listing of your wp-contents folder. If the index.php fi le didn’t exist, and your web server allowed directory listings, visiting http://example.com/wp-contents would display all of the fi les and folders in that directory. This can help hackers gain access to key fi les that might help exploit your website; for example if a vulnerability were discovered in a plugin, being able to view the list of directories in the WordPress plugin directory would quickly and easily inform an attacker if your site was a viable target.

If you are manually updating WordPress, make sure you avoid overwriting your wp-content directory.

Plugins Plugins are stored in the wp-content/plugins directory. A plugin can be a single fi le or multiple fi les inside of a folder. Any fi les inside the /plugins directory are scanned by WordPress to determine if the fi le is a properly formatted WordPress plugin. If the fi le is determined to be a plugin, it appears under the Plugins ➪ Installed Plugins SubPanel on your admin dashboard ready to be activated.

c02.indd 36 12/6/12 1:12 AM wp-content User Playground ❘ 37

NOTE Remember that to automatically deactivate a plugin, you can remove it from your /plugins folder. If an active plugin’s fi les are missing, WordPress deactivates the plugin before trying to render your website.

Your wp-content directory might also include a /mu-plugins directory. Must-use (mu) plugins are plugins that are automatically enabled in WordPress. Any plugins that exist in this folder will be executed just like a standard activated plugin. The major difference is mu-plugins cannot exist in a subdirectory or they will be ignored. To learn more about mu-plugins visit http://codex .wordpress.org/Must_Use_Plugins. You’ll be revisiting plugins in Chapter 8, “Plugin Development.”

Themes Themes are stored in the wp-content/themes directory. Each theme must exist in its own subdirectory and must consist of the proper template fi les for WordPress to recognize it as a usable theme. At a minimum, an index.php and a style.css fi le must exist in the theme directory, along with proper tagging to display under the Appearance ➪ Themes SubPanel on your admin dashboard. WordPress can store as many themes in this directory as your server allows. You can easily view a preview of any theme, or activate a new theme, under the Appearance ➪ Themes SubPanel. You’ll cover themes in much more detail in Chapter 9.

Uploads and Media Directory WordPress stores uploaded media in the wp-content/uploads folder. This directory does not exist in a default installation of WordPress. The /uploads directory is created the fi rst time you successfully upload a fi le to WordPress. By default WordPress stores uploads in month- and year-based folders. So your uploaded image would be stored like so:

/wp-content/uploads/2012/06/image.png

Before you can upload any images or fi les in WordPress, you need to set the /wp-content directory to be writable. When you upload your fi rst image, WordPress auto-creates the/uploads directory and any needed subdirectories. After you have successfully uploaded your fi rst image, reset the /wp-content permissions to not be writable, typically 755. Currently, there is no way to import images uploaded via FTP into the WordPress Media Library. If making the uploads directory writeable is not an option, there are plugins available (such as NextGen Gallery, described in detail in the Custom Directories section that follows) that include this functionality. WordPress Multisite stores upload media in a different manner. Instead of one uploads directory, Multisite creates a blogs.dir directory. Inside this folder are multiple subdirectories named with an ID. This ID is the blog ID the folder is attached to. Every site in a Multisite network has a unique

c02.indd 37 12/6/12 1:12 AM 38 ❘ CHAPTER 2 CODE OVERVIEW

blog ID. You’ll cover this in more detail in Chapter 10. For example, your fi rst WordPress Multisite site upload directory would look like this:

/blogs.dir/1/files/

This helps keep individual site uploads separated and easier to maintain.

Upgrade Directory The wp-content/upgrade directory is automatically created by WordPress when you use the automatic update process. This folder is used by WordPress to store the new version of WordPress that is downloaded from WordPress.org. The compressed WordPress download is extracted in this folder prior to the update. This folder should remain untouched for automatic updates to process successfully. If this directory is deleted, WordPress re-creates it the next time you run the auto-updater.

Custom Directories Some plugins that require a lot of custom fi les will store those fi les in a directory in your wp-content folders.

The Super Cache plugin (http://wordpress.org/extend/plugins/wp-super-cache/) creates a / wp-content/cache directory to store all of the cached pages created for your website. A cached page is simply a fully generated page on your website saved as a static HTML fi le. Instead of generating the page each time a user clicks one of your links, the cache plugin serves up the static HTML fi le to the visitor. This dramatically decreases WordPress load times and increases performance because pages aren’t generated on each view, but rather only when the cache is regenerated based on your settings.

The Super Cache plugin also adds two fi les to yourwp-content directory: advanced-cache.php and wp-cache-config.php. These two fi les are required for Super Cache to function correctly. When Super Cache is activated, it tries to create these two fi les. If it fails, a notice appears alerting you of this. The fi les exist in the Super Cache plugin directory and can be manually moved to the wp-content directory.

The most popular image gallery plugin, NextGen Gallery (http://wordpress.org/extend/ plugins/nextgen-gallery/), creates a /wp-content/gallery directory to store all of the images uploaded to your NextGen image galleries. Each gallery created is a subdirectory under /gallery. This helps keep your gallery image fi les very organized and easy to work with.

The WP-DB Backup plugin (http://wordpress.org/extend/plugins/wp-db-backup/) creates a / wp-content/backup-b158b folder (where b158b is a random string) to store local backups of your database. When you select the Save to Server option, all database backup fi les will be stored in this directory. It’s important to not delete your backups unless you are sure they are not needed anymore.

c02.indd 38 12/6/12 1:12 AM Summary ❘ 39

SUMMARY

In this chapter you covered downloading WordPress. You also covered confi guring key WordPress core fi les, wp-config.php and .htaccess, along with more advanced confi gurations for each. You also reviewed the wp-content directory and how WordPress interacts with custom directories. With that structural and confi guration view of WordPress, it’s time to learn how to create a local development environment so that you can begin customization and development without impacting a public site.

c02.indd 39 12/6/12 1:12 AM c02.indd 40 12/6/12 1:12 AM 3 Working with WordPress Locally

WHAT’S IN THIS CHAPTER?

➤ Developing locally ➤ Getting started with a local development environment ➤ Conﬁ guring a local development environment — tips and tricks ➤ Moving your local project to production

Now that you know how to obtain WordPress as well as what the basic lay of the land looks like, let’s take a look at how to get started doing something with WordPress, something beyond simply using WordPress as a website engine. Any user can install WordPress and use it to power a website, as you saw in Chapter 1, which is one of the reasons why WordPress has been so successful. As a developer, however, you need a full-featured but sandboxed place to experiment, try out new ideas, and fi gure out what has failed, without taking down a production or public site. As the fi rst step in building something, to take WordPress to the next step in your own projects, let’s look at the benefi ts of setting up a local development environment on your workstation or laptop. This chapter starts with a brief swing outside the realm of WordPress to talk about general software development.

BENEFITS OF WORKING LOCALLY

Developing locally is considered a best practice. In general, you do not want to be actively developing on a live production website because you could have visitors accessing the site at any time and development involves iterations of breaking code and making it work again. This is not the experience you want to provide to your visitors.

c03.indd 41 12/6/12 1:14 AM 42 ❘ CHAPTER 3 WORKING WITH WORDPRESS LOCALLY

What is “developing locally?” In short, it means you have a full WordPress installation to which you can make changes, add new code, and fail with impunity. It’s a sandbox, and it’s the fi rst element in a successful deployment cycle.

Typical Deployment Cycle Before diving into the reasons to develop locally fi rst, you’ll explain the different phases of deployment. Deployment involves taking your code from the base development versions that you feel are now ready for the world through staging and testing to a production website. In general, there are three levels. Some workfl ows will have more, but these three steps are the essentials: development, staging, and production. This is a basic software development workfl ow and applies to more than just WordPress development. First is the development environment, where you do all of your day-to-day work. As you’ll see in this chapter, this is typically your local workstation or laptop, but in some scenarios it might be a development location on a remote server. While it is best practice to develop your solution on a platform that is the same type of system as the production environment, this is not always practical. For example, your production web servers are high-end server class hardware running Linux, but because your developers need access to corporate resources such as Microsoft Exchange, they run Windows workstations for development. This is why the second tier is introduced, which is the staging or testing environment. After the developer has tested his solution on his development environment, he prepares to deploy it on a staging server. The intention of the staging server is to bridge the gap between the development environment and the target production environment without the risk of breaking the live website. As you will see later in this chapter, there are variances you have to consider when developing cross-platform code — that is, code that can run on Windows, Mac OS X, or Linux. This staging environment gives the developer an opportunity to make sure his code will run on a server that is similar to the production server. For WordPress development, this staging environment could be a secret test site on your production server. Finally, if the solution behaves as expected on the staging server, it can then be deployed to the live production server. The production server or servers are the ones that serve the website to the Internet. Using this three-tier workfl ow, developers are able to capitalize on the benefi ts of local development.

Why So Much Process? Now that you have a basic understanding of the workfl ow, you’ll circle back to why a developer should take these extra steps on the path to code deployment. While multiple phases seem at odds with a “get code working quickly” mantra, the benefi ts outweigh the overhead. First, as explained earlier, developing locally allows the developer to test and try things without breaking the live website. Truly, this can be one of the most important aspects of this system. Once your website has grown beyond the hobbyist audience, you want to minimize downtime. Developers should not be trying things on the live website. The second benefi t is privacy. Developing locally means your project is only available on your local workstation, or sometimes your local area network. You are in control of who is able to access it.

c03.indd 42 12/6/12 1:14 AM Tools for Component Administration ❘ 43

If you are developing on a public web server, however, while there are ways to restrict access, your potential audience is global. This privacy gives you the opportunity to try things and play around. Think of it as your own private WordPress sandbox with no one watching. For example, you might want to try the Ninja Warrior obstacle course or even the Wipeout obstacle course, but you do not want a global audience while you try to fi gure it out. There is no shame in attempting something and failing, but when working on a project, you probably don’t want it to be globally accessible while still in the development phase. While in development, your project could have security issues that have not been addressed yet and putting those on a production server puts the server at risk. Developing locally can save time and is often one of the biggest boosts to productivity. When working locally, you do not need a connection to the Internet to test your code. Your project is self-contained on your workstation. This also means you do not have to push your fi les to a remote server to test them. You simply need to save your edits and refresh your browser. The time waiting for FTP connections can add up. If you are developing a new theme, you can test your theme using different sets of content. For example, you may be building a custom theme for a specifi c project with an initial set of content, but you want to ensure that, in the future, new content added to the site is properly styled. Or you want to release your theme to the WordPress repository. While developing your theme on your local workstation, you can use different content than what is on the live site to make sure everything is formatted how you expect. This is part of the privacy of developing locally. Just because the initial website will have a certain content set for launch does not mean your local version must have the exact same content. This concept is covered in greater detail later in this chapter. Locally, you can run multiple instances of WordPress. Furthermore, each instance can be a different version of WordPress. This allows you to track changes to the core WordPress and make sure your code will continue to run on future revisions. For example, you can test your theme or plugin on one local site that is running the current version of WordPress, but you can also have a second WordPress site on your workstation that is running the beta version of the next release, or tracking the nightly development release. This helps you keep on top of changes to the WordPress core that might affect your project. There are many benefi ts and reasons to develop locally. In addition, for individual developers, there may be other reasons besides the privacy, security, and fl exibility benefi ts outlined here. Every developer will have to do his own cost benefi t analysis for each reason and determine if the risk or extra steps are worth the effort. At the end of this chapter, you will touch on some of the ongoing challenges with developing locally and moving your project through the development and deployment workfl ow. It is remarkably easy to set up a local WordPress development environment, using freely available tools that manage the major underlying components of the WordPress system: the web server with a PHP interpreter and the MySQL database.

TOOLS FOR COMPONENT ADMINISTRATION

Think about the prerequisites for WordPress, and then make a shopping list of the components you need for WordPress. WordPress is a web application. That means you need a web server. WordPress runs on PHP, a programming language for the web. That means your web server must support PHP.

c03.indd 43 12/6/12 1:14 AM 44 ❘ CHAPTER 3 WORKING WITH WORDPRESS LOCALLY

Apache is a good (and very popular) general-purpose web server that supports PHP, although there are many others that will work as well, including Microsoft IIS or Nginx. With WordPress version 3.2, the minimum version of PHP that is required is version 5.2.4. Ideally, you would like a web server that supports URL rewriting to make your permalinks work. Apache has a module called mod_rewrite to make this work. WordPress also needs a database to store the content of the site. WordPress only supports MySQL for the database and, as of version 3.2, the MySQL version must be 5.0 or greater. In addition, your PHP must have the appropriate MySQL libraries to make the database connection. You will also want a client to manage your database.

Getting Your Development Stack This sounds like a confusing and daunting list. But while many of us think of WordPress as the platform that you build your projects on, WordPress is, in turn, built on a platform. Commonly called the LAMP (Linux, Apache, MySQL, and PHP) stack, it has been the foundation for many Internet projects, including Facebook. And it is also the same foundation needed for WordPress. This means that the WordPress community is not the only one that has these requirements. As previously mentioned, this foundation is commonly called LAMP where the L stands for Linux. If you are running Linux as your workstation operating system, you can install the LAMP stack using your Linux distribution’s package management system. For example, if you are on a Debian or Debian derivative you could run apt-get install apache to install the Apache web server. A common trick is to install PHPMyAdmin as the MySQL client, that is, run apt- get install phpmyadmin . PHPMyAdmin is a web application that requires Apache, PHP, and MySQL, and because it is the MySQL client, it will install the appropriate libraries to connect PHP and MySQL. More than likely, you are not running Linux as your desktop operating system. You can install each component individually and connect all the moving parts for it to work. That would be the hard way. Luckily for us, there are some industrious people who have put together several packages that make installing and confi guring this LAMP foundation easy, and these packages exist for the various operating systems. If you are running Mac OS X, you can use the MAMP installer. We hope you can put together that this stands for Macintosh, Apache, MySQL, and PHP. You can download MAMP from http://www.mamp.info. Download MAMP, unpack it, and install it as you would any other Mac application. Once you drop it in your Applications folder, you can start MAMP and open your control panel. This is the control panel that controls the whole MAMP foundation, including your settings. One thing that we do not like about MAMP is that it does not use the default port for Apache. The standard for web servers to answer and respond is port 80, and browsers know this, which is why you never see an 80 in your browser’s address bar. MAMP, however, defaults to port 8888. That means that when you try to access your local web server, you will have to browse to http://localhost:8888 with your browser. Just keep that in mind as the examples in this book will be treated as though they’re running on the standard port 80.

c03.indd 44 12/6/12 1:14 AM Tools for Component Administration ❘ 45

If you are running a Windows workstation, you have a couple of options. Notably, there is WAMP and XAMPP. WAMP is Windows-specifi c and available from http://wampserver.com. WAMP, obviously, stands for Windows, Apache, MySQL, and PHP. XAMPP runs on Windows but is also cross-platform and is available from http://www.apachefriends.org. The X in XAMPP stands for cross-platform and the extra P is included because XAMPP includes PERL, another programming language. They are both good options. Download and install WAMP as you would any other Windows application. Once it is installed, you will have a new Windows system tray icon for WAMPSERVER that functions as your control panel. Note that this foundation is actually several different applications working together in unison to provide you with a web development platform that happens to power WordPress. These WAMP and MAMP installers are purely automating the wiring of these packages together for a general-purpose use. Each individual application also has individual confi guration fi les that you can adjust to meet your needs. Some common confi guration changes are covered later in this chapter.

Adding WordPress to the Local Install Now that you have a working foundation, you need to install WordPress. You will want to stop and consider how you intend on using this local development environment. Do you need only one installation of WordPress? If you want more than one, are you going to use subfolders or set up individual websites using virtual hosts? Are you going to use WordPress Multisite functionality for multiple sites? The next section discusses some of these options, but for now, take the simple route and set up one WordPress site. To install WordPress, you can use the same source code control method using git or subversion, as shown in the Chapter 2. Or you can use the traditional method of downloading the installation fi les from http://wordpress.org. Either way, once you have the WordPress core fi les you will need to put them in your web server’s document root. For MAMP, this is set up under the MAMP control panel ➪ Preferences ➪ Apache. You can accept the default or set this document root to wherever you would like. Commonly, Mac users put the document root in the Sites folder of their Mac.

The WAMP document root defaults to c:\wamp\www. You can quickly access this folder using the www directory option from the WAMPSERVER start tray option. Copy your WordPress core fi les to the appropriate document root folder on your workstation.

Now open a web browser and browse to http://localhost. Do not forget that if your local web browser is not on the standard port, you may need to add that to the address bar. Also, if you copied WordPress into a subfolder of the document root, you may need to add that suffi x to the URL — for example, http://localhost/ddamstra/Documents/www. If your web and database servers are confi gured correctly, WordPress will create its databases and edit confi guration fi les, and you should see the fi rst page of the WordPress installation, as shown in Figure 3-1.

c03.indd 45 12/6/12 1:14 AM 46 ❘ CHAPTER 3 WORKING WITH WORDPRESS LOCALLY

FIGURE 3-1: WordPress installation

As with any WordPress installation, you will need to have your database and database access credentials set up. Both WAMP and MAMP come with PHPMyAdmin to manage the MySQL. Use the WAMP or MAMP control panel to access PHPMyAdmin and set these up. Lastly, do the infamous 5-minute WordPress install, as covered in Chapter 1. If you have problems with getting your local development environment working, seek assistance through the appropriate support communities and documentation. While they are designed to be simple installations of the various components, every workstation is different and managing the confi guration of these assorted moving parts is outside the scope of this book, and only tangentially WordPress-related.

CONFIGURATION DETAILS

In the previous section, you walked through how to set up a local development environment. While that section didn’t include an in-depth discussion, the basic idea is there. This section is about extending that environment and covers some tips to help you get the most out of working locally. Again, some of these pointers are about the LAMP foundation itself. Here you will dig into confi guration options in more detail. This section walks you through managing the fi lesystem tree seen by the web server, enabling debug data, and creating virtual server names.

Managing the Web Server Document Tree In the previous section, you accepted the default document root for Apache. However, for various reasons, that may not be the best spot for your workfl ow or backup systems. For example, in your development shop with multiple web developers, you may remap your Apache document root to c:\www. This way, everyone’s document roots are all identical and it’s a top-level folder that is easily accessible. Conversely, on your personal laptop, you may remap your document root to C:\Users\ddamstra\Documents\www because the Documents folder is backed up when connected to your home local area network.

c03.indd 46 12/6/12 1:14 AM Conﬁ guration Details ❘ 47

Use caution when making changes to the confi guration. As mentioned many times, there are multiple moving parts involved and throwing one part out of alignment can have signifi cant consequences. MAMP allows you to change your document root through the control panel. With WAMP, you edit the confi guration fi le for Apache. This fi le is called httpd.conf and can be found in your WAMPSERVER control panel under the Apache fl yout. Change the line that reads document root to indicate your chosen location, as shown in Figure 3-2.

FIGURE 3-2: Apache document root

You will also need to change the Directory directive to match, as shown in Figure 3-3.

FIGURE 3-3: Apache Directory directive

c03.indd 47 12/6/12 1:14 AM 48 ❘ CHAPTER 3 WORKING WITH WORDPRESS LOCALLY

Using the WAMP control panel, you will need to restart Apache (or all services) for this change to take effect. If you previously had fi les in the old document root, you will need to move them to the new document root for them to be accessible. Take a moment to contemplate what you are publishing in your document root. You don’t want to publish any private or confi dential data. Consider which source code control system you are going to use. Is your source code control system also part of your deployment strategy? Make sure that if you are using a public repository such as GitHub that you do not push your wp-config.php fi le and expose your passwords. Likewise, if your development environment is accessible on your local area network, ensure you aren’t checking in confi guration fi les with sensitive information. Some source code control systems, notably subversion, store revisions in plain text in fi les in your project folder, potentially exposing credentials. This has happened to us on more than one internal penetration test exercise and the following is now part of your standard Apache confi guration. You can confi gure your Apache to not serve these .svn directories by adding the lines shown in Figure 3-4 to your httpd.conf fi le.

FIGURE 3-4: Apache block .svn ﬁ les

Enabling Debug Information When developing locally, you want to address as many potential errors and warnings as possible. At the very least, you need to be aware of them. For development, you should set your PHP error condition as high as possible to show these errors to you so that you can attend to them. As discussed in Chapter 13, this is the exact opposite of what you want to do on your production server. On your production server, you want to hide all the errors from your visitors. On your local workstation, you are the only visitor, so you want to see them all since the errors are what you are working on.

c03.indd 48 12/6/12 1:14 AM Conﬁ guration Details ❘ 49

You set your PHP error level in the php.ini fi le. With WAMP, you can access this fi le through the WAMP control panel, under the PHP fl yout. Set your error reporting directive to be E_ALL and E_STRICT, as shown in Figure 3-5.

FIGURE 3-5: PHP error level

Until PHP version 5.4, the strict warnings and notices have not been included in the E_ALL level. By setting the error reporting directive as mentioned, you will ensure that you are seeing the most error reporting possible, and coding to reduce these notices will ensure that you are providing the most PHP interoperability. Again, you will need to restart Apache to make this setting take effect. As previously mentioned, when developing on one operating system and deploying on another, you have to consider not all systems have the same PHP API. For example, the PHP $_SERVER[] has values on Windows machines that are not on Linux machines. Windows is not case sensitive in the fi lesystem, but Linux is. Developers have to remember that the target system may not be their development system. This is why you want the staging server to match the production server, so that discrepancies can be caught before being deployed. When developing locally, enable WordPress debugging. Similar to the PHP error reporting, this allows the developer to see and address WordPress issues. Likewise, this should always be disabled on production websites.

Enable WordPress debugging by editing your wp-config.php fi le and setting WP_DEBUG to true, as shown in Figure 3-6. Unlike the previous Apache and PHP settings, which were global to all sites on your workstation, this setting is per WordPress installation.

c03.indd 49 12/6/12 1:14 AM 50 ❘ CHAPTER 3 WORKING WITH WORDPRESS LOCALLY

FIGURE 3-6: WordPress debug

Handling Local and Production Database Out of the box, WordPress has confi guration for one database. When working locally, you want your development site to connect to your local MySQL so you do not risk messing up the production database. In other words, that is one of the reasons you are doing this.

A common method is to set the database host to be localhost and set your MySQL credentials and table name locally to the same as the production site. This is bad for security. Mark Jaquith offers an alternative solution that allows for both a production and a local workstation set of database access credentials on his site at http://markjaquith.wordpress.com/2011/06/24/ wordpress-local-dev-tips/. Essentially, he changes the wp-config.php fi le to look for an overriding set of credentials that exist on his development machine only. He then ignores this wp-config-local.php fi le in his source code control so that each developer can have his or her own controlled local credentials and so that this fi le never makes it to production.

Creating Virtual Local Server Names Initially, you set up WordPress in the document root of your local Apache. If you wanted more than one local website, you could set each website in its own folder. This works and you use it for many development sites. However, you can also set up each web server to respond to a local “fake” domain name. Sometimes, when moving to production, using this method makes the conversion from development to production easier. Here is how it works using some networking magic. Everyone is familiar with the common top-level domain names, such as .com, .net, and .org, and there are, in fact, many more with even more on

c03.indd 50 12/6/12 1:14 AM Conﬁ guration Details ❘ 51

the horizon. These fully qualifi ed domain names work through the DNS system where web browsers ask these Internet-accessible DNS servers for the IP address of the website domain you typed in. However, your web browser uses the DNS resolver to check a local fi le fi rst to see if there is predefi ned mapping. This fi le is called the hosts fi le. You can use this fi le and matching Apache confi gurations to make your workstation access local sites with fake fully qualifi ed domain names. There are a couple of approaches to this. Some developers set the domain name of the actual site they are working on to be their local workstation instead, pre-empting DNS requests. That means that until they revert these changes, they cannot access the live site, and all requests will go to the local site. For example, instead of having requests for mirmillo.com go to the server’s publicly accessible IP address, these requests are intercepted and are redirected to the localhost IP address, which is always 127.0.0.1. The other option is to set the development site with a fake name that is easy to replace in SQL during the deployment phase. In this case, we set the local development site to be mirmillo.local, which is an invalid top-level domain name (for now). This way, we can access mirmillo.com through traditional DNS and still work on our local development version by accessing mirmillo .local in our web browser. This is the example you are going to follow in this book. First, you have to set up your Apache to support virtual hosts. The actual confi guration here is going to vary depending on your Apache installation. Using WAMP, the fi rst step was to set up a virtual host in Apache. This is done by editing the httpd-vhosts.conf fi le found in C:\wamp\bin\ apache\Apache2.2.11\conf\extra. The default example comes with two sample virtual hosts. Change one of the existing examples to become your localhost virtual host. Then change the second example to match the settings you need for your local installation, such as mirmillo.local, as shown in Figure 3-7.

FIGURE 3-7: mirmillo.local virtual host

c03.indd 51 12/6/12 1:14 AM 52 ❘ CHAPTER 3 WORKING WITH WORDPRESS LOCALLY

Next, you have to direct Apache to include this fi le. This is done by editing your httpd.conf fi le as you have done previously in this chapter. As shown in Figure 3-8, uncomment the line to include the virtual host confi gurations settings.

FIGURE 3-8: Apache includes virtual host conﬁ g.

Next, edit your hosts fi le. On Mac OS X, this fi le is found in /private/etc/hosts and Linux has this fi le at /etc/hosts. On Windows, this fi le is C:\Windows\System32\drivers\etc. In short, this fi le is made up of IP address and domain name pairings. As shown in Figure 3-9, you can add a new mapping for mirmillo.local.

FIGURE 3-9: Hosts ﬁ le mapping for virtual host

c03.indd 52 12/6/12 1:14 AM Deploying Local Changes ❘ 53

Finally, restart Apache and browse to http://mirmillo.local to complete the WordPress installation, as you did in Chapter 1.

Local Theme and Plugin Development If you are developing a theme, one of the benefi ts of developing locally is that you do not have to use the content that will be on the live site. In fact, if you are developing a theme that you plan to release to the population at large, you should use a content fi ller to make sure you style the vast spectrum of content. For example you can use the WordPress sample content available at http://codex .wordpress.org/Theme_Unit_Test. There are several alternative sample content import fi les such as the one provided by WPCandy at http://wpcandy.com/made/the-sample-post-collection, but the WordPress Theme reviewers will use theirs to approve your theme to be in the repository. You can review the entire Theme Repository checklist at http://codex.wordpress.org/Theme_ Development_Checklist, and this is covered in Chapter 9, “Theme Development.” Say you are developing a theme and you want to test it with the sample content mentioned in the previous paragraph, but you also need to target specifi c content for the actual site you are developing the theme for. Here is a good use for WordPress Multisite. WordPress Multisite is covered in depth in Chapter 10, including how to set it up. But once you have it set up locally, WordPress Multisite allows you to leverage the same themes and plugins across multiple WordPress sites in a WordPress network. We set this up so that one of our WordPress sites has the sample content. Then we created a second site for the site-specifi c content. When you give this a try, you should network-enable the theme you are developing and activate it on both sites. This allows you to jump back and forth in your browser to two different WordPress content sets but only edit one set of theme fi les. Likewise, if you are developing a new plugin, test it in WordPress Multisite to make sure it works. You can also set up several virtual hosts on your machine running different versions of WordPress, both a few revisions back and also development releases to make sure your plugin will continue to work with the next update. Although we all preach to users to keep WordPress current, the reality is that some sites lag behind, either because of hosting restrictions, ignorance, or laziness. It’s important to make sure your plugin continues to work if you want people to use it. Also see Chapter 8, “Plugin Development.” Now that you have your new project working locally, and you have removed all the errors and notices from WordPress and PHP, you are ready to push it to a live server. In the next section, you will look at some of the challenges and tactics for pushing code live.

DEPLOYING LOCAL CHANGES

First, distinguish between the different types of objects you are deploying. There is code, which could be plugin code, or theme and theme assets. There is content, which is the website subject matter from the posts and pages and is stored in the database. Finally, there is the confi guration, which is also stored in the database. Deploying the code is easy. Developers do this every day. One of the advantages of PHP and WordPress is that you can generally drop code into the document root and it runs at the next

c03.indd 53 12/6/12 1:14 AM 54 ❘ CHAPTER 3 WORKING WITH WORDPRESS LOCALLY

request. Deploying code is simple and you can use your FTP client to do it. But please use SFTP, if possible, because it is a secure protocol, whereas FTP is not. Deploying the content and the confi guration is more diffi cult. WordPress uses fully qualifi ed links in all the content. So every internal HREF and menu item has the full domain name embedded. Likewise, the confi guration of the site is also tied to the domain name that WordPress was installed at. You can’t simply take a database dump and move it. There is, however, an intermediary step to change the domain names in the database export before importing it into the production site. Use caution here that you are not going to steamroll any updated content on the live site with your content from the development site. How exactly you do this in your situation is dependent on your exact needs, but overall, this process is very similar to a situation in which you are moving your site from one domain to another. The process is extensively documented in various websites, the WordPress codex at http://codex.wordpress.org/Moving_ WordPress, and many other tutorials. This is just one method. In short, this is how the process works for us, assuming you want to move all content from your development database to the live site. You are going to remove all the fully qualifi ed links from the content on your development site. All future content you add to the production site, once the content is moved, will be fully qualifi ed, but this is a method to make all the URLs root relative and then they will work on both your development site and the live site. For this process you use the wp-DBManager plugin by Lester Chan. This plugin allows you to make database backups and also perform SQL queries on the data. You could also use WordPress’s built-in database export functionality and PHPMyAdmin to do the same.

Pretend you are moving from the local development site mirmillo.local to the live production site of mirmillo.com. This is where using the “fake” domain name virtual host option mentioned previously comes in handy. Using the plugin, make a backup of your working test site. Download and save this backup fi le in case things go awry. Next, in the SQL page of the plugin, you will run the queries shown in Figure 3-10 to update the URLs in your site’s content. Essentially, you are removing the domain name from the URLs in the HTML code. Now export your content from your development site. Content export is found in your WordPress dashboard under Tools ➪ Export. Download this fi le. This is your movable content with root relative links. FIGURE 3-10: SQL queries to remove domain names

c03.indd 54 12/6/12 1:14 AM Summary ❘ 55

Import this content into your live site. The import functionality is found in your WordPress Dashboard under Tools ➪ Import. Again, be cautious that you do not overwrite newer content or content you want to keep. Truly, it is not a diffi cult process; it is just one that requires some planning and coordination. There are some developers who are working on tools to make this process easier. In particular, we have been keeping an eye on RAMP by Alex King’s Crowd Favorite, available online at http://crowdfavorite.com/wordpress/ramp/. While you haven’t tried it yet, it looks promising. The challenge is always that, when using WordPress as a Content Management System, users can and will log in to the production site and make changes — that’s the point. But in doing so, your development content gets out of sync. Ultimately, the goal will be to have a way to synchronize WordPress databases between live, staging, and development and be able to handle confl ict resolution. There is no silver bullet here, but it seems to be a challenge that many developers are working on.

SUMMARY

This chapter reviewed some of the reasons and processes for a proper development workfl ow. In addition, it covered how to enable a local WordPress development environment in your own private sandbox. Finally, you examined a process to push a development site to a production server. The next chapter digs into the core fi les of WordPress and reviews how WordPress works.

c03.indd 55 12/6/12 1:14 AM c03.indd 56 12/6/12 1:14 AM 4 Tour of the Core

WHAT’S IN THIS CHAPTER?

➤ Exploring the WordPress core ﬁ les ➤ Searching through core ﬁ les as reference ➤ Working with the WordPress Codex ➤ Understanding inline documentation

To understand how to extend WordPress properly, you must fi rst learn how the core of WordPress functions. This will help you learn what tools are available in the WordPress core to make your life easier. WordPress handles most of the tedious coding and logic problems for you. The WordPress core is the best resource for learning how WordPress works. The beauty of open source software is you have all of the code at your disposal. If you are ever unsure how a certain aspect of WordPress functions, just start digging into the code! The answers are all there; it’s just a matter of fi nding and understanding them.

WHAT’S IN THE CORE?

The WordPress core is powered by a set of fi les that are part of the original WordPress software download. These are required “core” fi les that WordPress needs to function properly. The core fi les are expected to change only when you upgrade WordPress to a newer version. The core does not include your custom fi les for plugins, themes, database settings, the .htaccess fi le, and so on. The core also does not include any media you have uploaded to WordPress. Basically, any fi les added to WordPress after installation are considered outside of the core.

c04.indd 57 12/6/12 1:15 AM 58 ❘ CHAPTER 4 TOUR OF THE CORE

The WordPress core fi les are primarily PHP fi les, but also contain CSS, JavaScript, XML, HTML, and image fi les. These fi les control everything about WordPress including how content pages are generated to display, loading the confi gured theme and plugins, loading all options and settings, and much more. In short, the core contains several major function types: ➤ Posts, pages, and custom content — Creating, storing, retrieving, and interacting with the majority of your WordPress content. The discussion of the loop that controls content display and ordering in Chapter 5 relies heavily on these functions. ➤ Metadata — Everything from tags and categories to user-created taxonomies. The data models used are explored in Chapter 7. ➤ Themes — Supporting functions for WordPress themes. Theme development and its relationship to these functions are discussed in Chapter 9. ➤ Actions, fi lters, and plugins — Framework for extending WordPress, covered in more detail in Chapter 8. ➤ Users and authors — Creating and managing access control to your site, and key to the security and enterprise use topics in Chapters 12 and 14. ➤ Feeds, formatting, and comments — These are discussed as needed throughout the book.

This chapter digs into these fi les as you explore the WordPress core fi les. Think of this chapter as your guidebook to the “how” of exploring the WordPress core; it is a fi eld guide companion to the WordPress Codex documentation for user-contributed discussion and explanation. It’s also impera- tive to be comfortable browsing and searching the core to complement the functional introduction provided here. An exhaustive list of every WordPress function is not included here, both because the list changes and evolves as the WordPress core undergoes continuous development, and because the goal here is to convey developer and deployer expertise and not to summarize the Codex. WordPress comes packaged with two plugins: Akismet and Hello Dolly. These two plugins exist in your plugins directory inside wp-content. Even though these two plugins are a part of the WordPress core fi le package download, they are not considered core functionality because they must be activated to function and can easily be removed. WordPress also comes packaged with three core themes: Twenty Ten, Twenty Eleven, and Twenty Twelve. Twenty Twelve is the default theme on a fresh installation of WordPress. As with the included plugins, these theme fi les are not considered core functionality because they can easily be replaced with any theme that you want to use on your website.

USING THE CORE AS A REFERENCE

To use the WordPress core as a reference, you need to understand what to expect in the core fi les. Most WordPress core fi les contain documentation in the form of code comments. Typically, a code comment is displayed in the header of the fi le and gives an overall summary of the core fi le you are viewing.

To see this fi rst-hand, open the wp-login.php fi le located in the root directory of WordPress. You’ll notice the top of the fi le has a header comment describing the fi le’s function:

c04.indd 58 12/6/12 1:15 AM Using the Core as a Reference ❘ 59

/** * WordPress User Page * * Handles authentication, registering, resetting passwords, forgot password, * and other user handling. * * @package WordPress */

All core fi les, other than images, can be viewed using a text editor program. Depending on your default program settings, you may need to open up your text editor fi rst and then open the fi le rather than just opening up the fi le directly. It’s also helpful to use a text editor that has syntax highlighting, meaning PHP syntax would be highlighted to help you read the code easier.

There is a full list of compatible text editors on the WordPress.org Codex at http://codex .wordpress.org/Glossary#Text_editor.

Inline Documentation Nearly all WordPress core fi les contain inline documentation in PHPDoc form. PHPDoc is a standardized method of describing a function’s usage in PHP comment form. This means each function is explained in detail directly before the function in a comment block. The following is the defi ned template for documenting a WordPress function:

/** * Short Description * * Long Description * * @package WordPress * @since version * * @param type $varname Description * @return type Description */

This is amazingly helpful in understanding how functions work. The comment includes a short and long description. It also includes the version of WordPress it was added in. This helps distinguish new functions added to WordPress when a new version is released. Available parameters are also listed along with the parameter data type. A data type is the type of data that is required for the parameter. For example, an ID parameter would likely use the int (integer) data type. The fi nal piece of information is the return value. The return value data type is also listed. All new functions added to WordPress are documented using the preceding template. For more information on inline documentation in WordPress, see this Codex article: http://codex.word press.org/Inline_Documentation.

c04.indd 59 12/6/12 1:15 AM 60 ❘ CHAPTER 4 TOUR OF THE CORE

Finding Functions Looking up a function in the core is the quickest way to learn how a specifi c WordPress function works. You can see exactly what parameters are allowed to be sent to the function, as well as what the function actually does and what the return values are. To start, make sure you have downloaded the latest version of WordPress locally to your computer. You will search these fi les as a reference for WordPress. Open up any text editor you have that can search fi les (TextPad for Windows and Textmate for Mac are recommended). When searching for a function, you want to eliminate calls to that function from your search. Do this by including the word “function” at the start of your search, as in function wp_head. Not everything in WordPress is a function, but this is a good place to start. If you don’t fi nd any matches, remove “function” from the beginning of your search. Also remember to set your text editor to search all fi les (*.*), not just .txt fi les.

Let’s look at the is_super_admin() function. This function is used to check if a user is a super admin in WordPress Multisite. You need to know exactly what values the function expects before you can use it. Open your text editor and search all fi les in WordPress for function is_super_admin. The search should produce one result in wp-includes/capabilities.php:

function is_super_admin( $user_id = false ) {

Right away, you notice one parameter that can be sent to this function: $user_id. Notice the inline documentation listed directly above the function. In this case, the is_super_admin() documentation looks like this:

/** * Determine if user is a site admin. * * @since 3.0.0 * * @param int $user_id (Optional) The ID of a user. Defaults to the current user. * @return bool True if the user is a site admin. */

This is an extremely valuable block of content. The comment has a short description about what the function does, in this case “Determine if user is a site admin.” The comment also notes when the function was added (since version 3.0.0). There is also information about the single parameter, including the parameter type, what the parameter is responsible for, and the fact that the parameter is optional in this case. The comment also details what the expected return values will be. In this case, the function will return True if the user is a site admin and False if not. This alone is enough information to understand how this function works, but let’s dig into the code for a better understanding. The fi rst few lines look like this:

if ( $user_id ) $user = new WP_User( $user_id ); else $user = wp_get_current_user();

c04.indd 60 12/6/12 1:15 AM Using the Core as a Reference ❘ 61

Based on the PHPDoc comment above the function, you know the $user_id parameter is optional, so this code shows what happens if a $user_id parameter is not passed to the function. The preceding if statement checks if the $user_id variable contains a value. If it does, the WordPress User class, WP_User, is called to retrieve the user data for that user ID. If the $user_id variable is empty, the wp_get_current_user() function is called to get the user data for the currently logged in user.

Next, the function checks that the $user data actually exists before proceeding and, if not, will return false.

if ( ! $user->exists() ) return false;

Now that you know the $user data exists, you need to check if that user is actually a super admin:

if ( is_multisite() ) { $super_admins = get_super_admins(); if ( is_array( $super_admins ) && in_array( $user->user_login, $super_admins ) ) return true; } else { if ( $user->has_cap('delete_users') ) return true; }

Let’s break down this if statement a bit:

if ( is_multisite() ) {

This if statement checks that Multisite is actually running in WordPress by calling the is_mul- tisite() function. Super admins will only exist if the Multisite feature of WordPress has been enabled.

Now that WordPress has determined Multisite is running, the function calls get_super_admins() to retrieve an array of all super admins in WordPress using the following code:

$super_admins = get_super_admins();

The $super_admins variable is now an array of all super admin login usernames. The next line is the most important line in this function. This is the code that actually checks that a user is a super admin in WordPress:

$super_admins = get_super_admins(); if ( is_array( $super_admins ) && in_array( $user->user_login, $super_admins ) ) return true;

Before working with an array, you always want to verify the variable is an actual array using the is_array() PHP function. The second part of this line of code uses the in_array() PHP function to check if the user’s login exists in the super admin array. If it exists, the user is a super admin and the function returns true.

c04.indd 61 12/6/12 1:15 AM 62 ❘ CHAPTER 4 TOUR OF THE CORE

If the is_multisite() check covered earlier returns false, the function will execute the following else code:

} else { if ( $user->has_cap('delete_users') ) return true; }

The preceding code checks if the user has the delete_users capability. By default, this capability is assigned to regular administrator accounts in WordPress. If Multisite is disabled in WordPress, but you are an administrator, this code will return true when calling the is_super_admin() function. The fi nal line of code in the function is:

return false;

This code basically says that if any of the checks in the is_super_admin() function fail, return false. This is more of a safety measure to be certain a true or false value is always returned. After viewing this example, it should be more apparent how useful the WordPress core code can be. You learned exactly how this function works by exploring the source code. All the answers to your questions exist within the core so it’s essential to have a good understanding of how to utilize the core to your advantage.

Exploring the Core The WordPress core has certain fi les that contain many of the most popular WordPress functions. These functions are used for all WordPress APIs and can be used in any custom plugin or theme. The following sections detail the WordPress core fi les that contain key pieces of code for working with WordPress. All of the fi les listed in the section that follows are located in the /wp-includes directory of WordPress.

Functions.php The functions.php fi le contains the main WordPress API functions. These functions are used to easily interact with WordPress using a standardized method. Plugins, themes, and the WordPress core all use these functions:

➤ current_time — Retrieves the current time based on specifi ed type. ➤ force_ssl_login — Requires SSL (https) login to WordPress. ➤ wp_nonce_field — Displays a nonce hidden fi eld for forms. A nonce fi eld is used for verifi cation purposes when submitting and processing data in WordPress. This is a critical step in securing your code. ➤ absint — Converts value to nonnegative integer.

c04.indd 62 12/6/12 1:15 AM Using the Core as a Reference ❘ 63

Option.php The option.php fi le contains the main WordPress Options API functions. These functions are used for the following:

➤ add_option, update_option, get_option — Functions to create, update, and display a saved option. ➤ set_transient, get_transient, delete_transient — Functions to create, retrieve, and delete transients in WordPress. A transient is an option with an expiration time. When the expiration time is hit, the transient is automatically deleted in WordPress. ➤ add_site_option, update_site_option, get_site_option — Functions to create, update, and display site options. If Multisite is enabled, function returns the network option; if not, the standard site option is returned.

Formatting.php The formatting.php fi le contains the WordPress API formatting functions. These functions format the output in many different ways:

➤ esc_attr — Used to escape a string for HTML attributes. ➤ esc_html — Used to escape a string for HTML. ➤ esc_url — Used to check and clean a URL. ➤ sanitize_text_field — Sanitizes a string from user input or from the database. ➤ is_email — Verifi es that an e-mail is valid. ➤ capital_P_dangit — Famous fi lter that forces the P in WordPress to be capitalized when displaying in content.

Pluggable.php The pluggable functions fi le lets you override certain core functions of WordPress. WordPress loads these functions if they are still undefi ned after all plugins have been loaded. Some of the more commonly used functions include:

➤ wp_mail — Sends e-mail from WordPress. ➤ get_userdata — Returns all user data from the specifi ed user ID. ➤ get_currentuserinfo — Returns user data for the currently logged-in user. ➤ wp_set_password — Updates a user’s password with a new encrypted one. ➤ wp_rand — Generates a random number. ➤ wp_logout — Logs out a user, destroying the user session. ➤ wp_redirect — Redirects to another page. ➤ get_avatar — Returns the user’s avatar.

c04.indd 63 12/6/12 1:15 AM 64 ❘ CHAPTER 4 TOUR OF THE CORE

Plugin.php The plugin.php fi le contains the WordPress Plugin API functions, including:

➤ add_filter — Hooks that the WordPress core launches to fi lter content before displaying on the screen or saving in the database. ➤ add_action — Hooks that the WordPress core launches at specifi c points of execution. ➤ register_activation_hook — Hook called when a plugin is activated. ➤ register_deactivation_hook — Hook called when a plugin is deactivated. ➤ plugin_dir_url — Returns the fi lesystem directory path for the plugin. ➤ plugin_dir_path — Returns the URL for the plugin.

User.php The user.php fi le contains the WordPress User API functions, including:

➤ get_users — Returns a list of users matching criteria provided. ➤ add_user_meta, get_user_meta, delete_user_meta — Used to create, retrieve, and delete user metadata. ➤ username_exists — Checks if a username exists. ➤ email_exists — Checks if an e-mail address exists. ➤ wp_insert_user and wp_update_user — Create and update a user account.

Post.php The post.php fi le contains the functions used in the post process of WordPress, including:

➤ wp_insert_post — Creates a new post. ➤ get_posts — Retrieves a list of the latest posts’ matching criteria. ➤ add_post_meta — Creates metadata (custom fi eld data) on a post. ➤ get_post_meta — Retrieves metadata (custom fi eld data) on a post. ➤ get_post_custom — Returns a multidimensional array with all metadata (custom fi eld) entries for a post. ➤ set_post_thumbnail — Sets a featured image on a post. ➤ register_post_type — Registers a custom post type in WordPress.

The plugin registration functions add_filter() and add_hook() are key to extending how WordPress processes content, and these functions let you extend the basic content data structures used by WordPress. We cover custom post types and their data management in detail in Chapter 7.

c04.indd 64 12/6/12 1:15 AM Using the Core as a Reference ❘ 65

Taxonomy.php The taxonomy.php fi le contains the functions used by the WordPress Taxonomy API. Taxonomies are used to manage the hierarchical relationships of metadata such as categories and tags (described in Chapter 6) and can also be extended, as you’ll explore in Chapter 7. Functions in this fi le include:

➤ register_taxonomy — Registers a custom taxonomy in WordPress. ➤ get_taxonomies — Returns a list of registered taxonomies. ➤ wp_insert_term, wp_update_term — Insert or update a taxonomy term based on arguments provided.

There are many more core functions that can be used when developing custom themes and plugins for WordPress. Take a few minutes and explore the core fi les inside /wp-includes. This directory contains most of the WordPress API core function fi les. To learn more about any function listed here, open up the corresponding fi le and view the source code. Remember that each function will have inline documentation explaining how to utilize the function correctly. We cover the Plugin API functions in more detail in Chapter 8. The core functions used by themes are covered in Chapter 9.

Deprecated Functions When a new version of WordPress is being developed, certain functions may become deprecated. A deprecated function means the function is not removed from WordPress, but it should not be used in your plugins and themes going forward. Typically in such a case, a new function has been created to replace the deprecated function. A function may be deprecated in WordPress for many different reasons, but the most common is that the function needs a complete rewrite to better handle the feature it adds to WordPress. WordPress contains a fi le to store all functions that have been deprecated over the years. WordPress is known for having superior backwards compatibility. This means that when a new version of WordPress is released, a strong focus it put on backwards compatibility to verify new features and functions will not break existing sites running WordPress, even if the features in use are considered deprecated.

Let’s look at the inline documentation for the get_current_theme() deprecated function:

/** * Retrieve current theme name. * * @since 1.5.0 * @deprecated 3.4.0 * @deprecated Use (string) wp_get_theme() * @see wp_get_theme() * * @return string */

c04.indd 65 12/6/12 1:15 AM 66 ❘ CHAPTER 4 TOUR OF THE CORE

You’ll notice a few additional comment lines for deprecated functions. The fi rst is the @deprecated line stating in what version of WordPress the function was deprecated, in this case v3.4. The second is @see which tells you what function should be used instead, in this case wp_get_theme().

The deprecated.php fi le is a very important fi le to check when a new version of WordPress is released. If a common function is deprecated, you should immediately stop using it and even consider updating your old code to use the replacement. Generally speaking deprecated functions are usually not removed from WordPress core, but there is no guarantee a deprecated function won’t be removed in a future release.

WORDPRESS CODEX AND RESOURCES

WordPress has many different online resources that are extremely useful when learning and working with WordPress. These resources should be bookmarked for quick reference and are used by begin- ners and experts alike.

What Is the Codex? The WordPress Codex is an online wiki for WordPress documentation located on WordPress.org. WordPress.org describes the Codex as an “encyclopedia of WordPress knowledge.” You can visit the WordPress Codex by going to http://codex.wordpress.org or by clicking the Docs tab in the header of WordPress.org. The Codex is a wiki-based website, which means anyone can create, edit, and contribute to the articles within the Codex. The Codex is jam-packed with useful knowledge covering all aspects of WordPress. From, “Getting Started with WordPress,” to more advanced developer topics, the Codex is an essential resource for anyone looking to learn more about WordPress. The Codex is available in many different languages. To fi nd a Codex version translated in your language, visit the Multilingual Codex page at http://codex.wordpress.org/Multilingual_ Codex. You can also contribute to the Codex and help expand on any language or create your own language if it is not listed.

Using the Codex The Codex can be used in many different ways. The most common method is to search the Codex using the search box in the header, or you can visit http://wordpress.org/search/ to easily search through the Codex for appropriate articles matching your search criteria. The WordPress.org search is powered by Google Custom Search, as shown in Figure 4-1. The search results returned are from all of WordPress.org, not just the Codex, so it’s important to keep that in mind. There is a lesser known Codex-only search located at http://codex.wordpress.org/ Special:Search.

c04.indd 66 12/6/12 1:15 AM WordPress Codex and Resources ❘ 67

FIGURE 4-1: WordPress.org search

You can also navigate through the index of articles on the Codex homepage. These articles are organized by topic and generally ordered by level of diffi culty. There is also a topic toward the top for the latest version of WordPress. The articles here cover new features, compatibility tests for plugins and themes, installing, upgrading, and support for the new version. An extensive glossary of terms is available for the Codex. This can help familiarize you with common words used throughout the Codex. You can view the offi cial Codex Glossary at http://codex.wordpress.org/Glossary. Another search method is to use the quick index. This index allows you to look up an article by the fi rst letter of the article’s title. You can fi nd the quick index at http://codex.wordpress.org/ Codex:Quick_index.

A WordPress Lessons page is also featured in the Codex at http://codex.wordpress.org/ WordPress_Lessons. This page provides lessons on how to learn specifi c elements of WordPress. The lessons are organized by topic and are a great place to start if you are unsure what to read fi rst.

Function Reference WordPress functions are described in the Codex with an individual Function Reference page for each WordPress API function available. These pages explain in detail exactly how a WordPress

c04.indd 67 12/6/12 1:15 AM 68 ❘ CHAPTER 4 TOUR OF THE CORE

function works, as shown in Figure 4-2. Bookmark this page for a quick reference on WordPress functions and their capabilities. The offi cial Function Reference is located at http://codex.word press.org/Function_Reference.

FIGURE 4-2: Function reference for get_userdata

Think of the Function Reference as an online and expanded version of a function’s inline documentation. The reference has a description explaining how the function works and how it is used. The individual parameters are listed along with data types and a description of each. The most useful section of the Function Reference is the examples toward the bottom. The examples make it very easy to see exactly how to use the function. The get_userdata example is shown here:

user_login . "\n"; echo 'User level: ' . $user_info->user_level . "\n"; echo 'User ID: ' . $user_info->ID . "\n"; ?>

This example shows how to load specifi c user data for user ID 1. The example output is as follows:

Username: michael_myers User Level: 10 User ID: 1

This is a simple example, but this, along with the additional reference information, can help you easily learn a new function and how to use it properly in your code.

c04.indd 68 12/6/12 1:15 AM WordPress Codex and Resources ❘ 69

The fi nal Function Reference topic lists related functions. This can help you identify a similar function that may accomplish that task you are working on. For example, the wp_insert_post() function lists wp_update_post() and wp_delete_post() as related functions. The majority of the WordPress API functions are well documented, but not all functions have a Function Reference page in the Codex. Any function displayed in red on the Function Reference homepage currently has no documentation. This is an ongoing community project so expect all functions to be fully documented in the Codex eventually.

NOTE Contributing to the Codex is a great way to get involved in WordPress. You don’t need to be an advanced developer to contribute code examples, descriptions, and additional information about various features and functions in WordPress.

WordPress APIs WordPress features many different APIs that help interact with WordPress. Think of the APIs as gateways that let you add code or retrieve external content within WordPress without violating the “don’t the hack core” maxim: most APIs insert references to non-core code that will be added to the wp-content directory by registering its entry points with WordPress. Each API is documented in the Codex along with functions used in the API. An API is a set of predefi ned functions available for use in themes and plugins. The following is a list of the most common WordPress APIs: ➤ Plugin API — Used for custom plugin development. The Codex features an extensive Plugin API documentation page. There is an introduction to Hooks, Actions, and Filters, which are the primary ways to interact with WordPress from a custom-built plugin. The Plugin API page links to the Function Reference pages for available API functions, which are located in /wp-includes/plugins.php.

http://codex.wordpress.org/Plugin_API

➤ Widgets API — Used to create and maintain widgets in your plugin. The widget will automatically appear under the Appearance ➪ Widgets SubPanel and can be used on any defi ned sidebar on your theme.

http://codex.wordpress.org/Widgets_API

➤ Shortcode API — Used for adding shortcodes in your plugin. A shortcode is a macro code added to a post. This allows a plugin to grab that shortcode and execute specifi c commands and display elements in place of it in your post. Shortcodes can also accept parameters to alter the output. An example core WordPress shortcode is [gallery]. A d d i n g [gallery] to your post automatically displays all images uploaded to that post in a gallery style. When editing a post, you will see the [gallery] shortcode, but viewing it on the public side of your website displays the actual gallery of images.

c04.indd 69 12/6/12 1:15 AM 70 ❘ CHAPTER 4 TOUR OF THE CORE

http://codex.wordpress.org/Shortcode_API

➤ HTTP API — Used for sending an HTTP request from WordPress. This API is a standardized method to grab the content of an external URL. Basically, it takes the provided URL and tests a series of PHP methods for sending the request. Depending on the hosting environment, WordPress uses the fi rst method it deems to be confi gured correctly to make the HTTP request. The current HTTP API PHP methods tested are cURL, Streams, and FSockopen. The methods are also checked exactly in that order. You can use the Core Control plugin (http://wordpress.org/extend/plugins/Core-control/) to specifi cally choose which method is used for all HTTP requests. Using the HTTP API, you could easily interact with the Google Maps API to dynamically generate maps and plots. The HTTP API can also easily interact with the Twitter API, allowing you to post/read tweets directly from WordPress.

http://codex.wordpress.org/HTTP_API

➤ Settings API — Used for creating a settings page. This API is used for creating and managing custom options for your plugins and themes. The main advantage of using the Settings API is security. The API sanitizes all of the setting data saved by the user. This means no more worrying about nonces, data validation, and cross-site scripting (XSS) attacks when saving setting data. This is much easier than the old method of data validation, which you had to use each time you needed to save settings in a plugin.

http://codex.wordpress.org/Settings_API

➤ Options API — Used for storing option data in the WordPress database. The Options API provides an easy way to create, update, retrieve, and delete option values.

http://codex.wordpress.org/Options_API

➤ Dashboard Widgets API — Used for creating admin dashboard widgets. Widgets added from the API automatically contain all jQuery features that the core admin dashboard widgets have, including drag/drop, minimize, and hiding via screen options.

http://codex.wordpress.org/Dashboard_Widgets_API

➤ Rewrite API — Used for creating custom rewrite rules. This API allows you to create custom rewrite rules just as you would in your .htaccess fi le. You can also create custom permalink structure tags (that is, %postname%), add static endpoints (that is, /my-page/), and even add additional feed links. The Rewrite API functions are located in /wp-includes/rewrite.php at http://codex.wordpress.org/Rewrite_API.

Remember that all WordPress APIs can be used in custom plugin and theme development. This is the primary method of extending WordPress with additional features and functionality. Utilizing the preceding APIs creates an easy and standardized way of interacting with WordPress.

c04.indd 70 12/6/12 1:15 AM Don’t Hack the Core! ❘ 71

For more information on all WordPress APIs visit the Codex page at http://codex.wordpress .org/WordPress_API's.

Codex Controversy As with any wiki, there will always be controversy over the accuracy of the articles in the Codex. One problem that has plagued the Codex is the freshness of the articles. WordPress is being developed at a decent pace and thus the Codex needs to keep up that pace in order to be accurate. Unfortunately, that doesn’t always happen, and some material is outdated. The WordPress Codex is a community project, so you can easily create an account and start helping out! Contributing to WordPress is covered in Chapter 16. Another problem that exists within the Codex is the organization of the content. Currently, there is so much information in the Codex that it can be hard and confusing to fi nd the answers you are looking for. Again, one of the motivations for this introduction to the WordPress core is to provide you with a map to help narrow the scope of your searches and to introduce related functional topics.

DON’T HACK THE CORE!

Whereas exploring the WordPress core and using it as a reference is highly encouraged, hacking the core is not. Hacking the core means making any changes to the core fi les of WordPress. A change could be as simple as one line of code, but a hack is a hack and doing so could cause major problems down the road.

Why Not? Hacking the WordPress core can make it very diffi cult to update to the latest version of WordPress. Keeping WordPress current is an important step in overall website security. If any security vulnerability is discovered, a patch is typically released very quickly. If you can’t update because you have modifi ed core fi les, you are opening up your website to these security vulnerabilities, and you increase the likelihood that your website will be hacked. Hacking the core can also lead to an unstable website because many parts of WordPress rely on other parts to function as expected. If you make changes to those parts, it could break something completely unrelated to what you have changed. Security is another reason why you shouldn’t hack the core. WordPress core is viewed and scrutinized by security experts all over the world. By hacking the core, you are relying on your own expertise to make your hacks secure. If you don’t understand the many different ways a hacker can exploit your code, you might end up creating a security vulnerability within the core of WordPress. The fi nal reason why you should never hack the core is compassion: that is, compassion toward the developer who comes after you to maintain the website. Most websites will change developers over the years so there is no guarantee you will be working on a particular website fi ve years from now. Imagine the developer that follows you trying to determine what core fi les were hacked to make the website function. This can be a nightmare for any developer and it puts the website owner in a bad position because most developers will refuse to work on a hacked version of WordPress. If you hack

c04.indd 71 12/6/12 1:15 AM 72 ❘ CHAPTER 4 TOUR OF THE CORE

the core, you are building dependencies that will either be misunderstood or hidden, and when the WordPress core is upgraded for this site, the hacked core will break in silent, evil, or loud ways.

Alternatives to Hacking the Core Any feature or functionality that does not exist in WordPress can be added with a plugin. Sometimes a core hack may be the easy answer, but in the long run, it will make your life harder. (We have yet to come across a feature we needed that we couldn’t incorporate with a plugin.) WordPress is extremely fl exible, which is one of its major strengths, and therefore the core should never be hacked. Don’t hack the core! If you are fascinated by the WordPress core and its intricacies, you should join the WordPress Developer Community and get involved fi xing bugs and contributing to the core build of WordPress. This is covered in detail in Chapter 16.

SUMMARY

In this chapter you covered a tour of the WordPress core software. You explored what’s in the core, how to use the core as a reference when developing for WordPress, and how to determine what functions are deprecated each release. You also learned about the WordPress Codex and available APIs in WordPress. Now that you understand the core of WordPress, it’s time to learn how to utilize the WordPress Loop to customize the display of content.

c04.indd 72 12/6/12 1:15 AM 5 The Loop

WHAT’S IN THIS CHAPTER?

➤ Understanding the ﬂ ow of the Loop and where it can be used ➤ Determining content display using the Loop ➤ Customizing the Loop with diff erent granularities of data access ➤ Using template tags ➤ Understanding global variables and their relationship to Loop processing ➤ Working outside of the Loop The Loop refers to how WordPress determines what content (posts, pages, or custom content) to display on a page you are visiting. The Loop can display a single piece of content or a group of posts and pages that are selected and then displayed by looping through the content; thus, it’s called the Loop. This is how WordPress displays blog posts by default. The Loop selects posts from the MySQL database based on a set of parameters, and those parameters are typically determined by the URL used to access your WordPress website. For example, the homepage might show all blog posts in reverse chronological order by default. A category page, accessed via a URL such as http://example.com/category/zombies, shows only blog posts assigned to that category, in this case pages put into the zombies category. An archive page shows only blog posts that are dated with that particular month and year. WordPress maps nearly every parameter about your posts into a selection variable, providing the basis for an equally wide number of different ways to alter the Loop’s content selection algorithm. It is very easy to customize what content is displayed, and where, on your website with a thorough understanding of how the Loop translates a URL into what you see when you access that link.

c05.indd 73 12/6/12 1:28 AM 74 ❘ CHAPTER 5 THE LOOP

This chapter discusses how the Loop works, where the Loop can be used, and the logical fl ow of the Loop. It also covers how to customize the Loop using the many different functions and data access methods available in WordPress. Global variables that maintain the current state are also discussed along with working outside of the Loop.

UNDERSTANDING THE LOOP

Understanding how the Loop functions will help you understand how you can control it. Controlling the Loop to display exactly the content you want will be one of your most used tools in developing WordPress-powered websites. Because the Loop is at the heart of every WordPress theme, being able to customize the display content opens up the doors to making WordPress look and act however you want. To understand the Loop, it helps to break down the steps WordPress takes to generate a page’s content: 1. The URL is matched against existing fi les and directories in the WordPress installation. If the fi le is there, it is loaded by the web server. WordPress doesn’t actually get involved in this decision; it’s up to your web server and the .htaccess fi le created by WordPress to decide if the URL is something handled by the web server or to be turned into a WordPress content query. This was covered in the discussion of permalinks in Chapter 2. 2. If the URL doesn’t load a WordPress core fi le, it has to be parsed to determine what content to load. The web server starts by loading the WordPress core through index.php to begin the setup for the Loop. For example, when visiting a specifi c tag page such as http://example.com/tag/bacon, WordPress will determine that you are viewing a tag and load the appropriate template, select the posts saved with that tag, and generate the output for the tag page. 3. The translation of URL-to-content-selection magic happens inside of the parse_ query() method within the WP_Query object that WordPress created early on in its processing. WordPress parses the URL fi rst into a set of query parameters that are described in the next section. All query strings from the URL are passed into WordPress to determine what content to display, even if they look like nicely formatted pathnames. If your site is using pretty permalinks, the values between slashes in those permalinks are merely parameters for query strings. For example, http://example.com/tag/bacon is the same as http://example.com?tag=bacon, which conveys a query string of tag with a value of bacon. 4. WordPress then converts the query specifi cation parameters into a MySQL database query to retrieve the content. The workhorse here is the get_posts() method within the WP_Query object that is described later in this chapter. The get_posts() method takes all of those query parameters and turns them into SQL statements, eventually invoking the SQL string on the MySQL database server and extracting the desired content. The content returned from the database is then saved in the WP_Query object to be used in the WordPress Loop and cached to speed up other references to the same posts made before another database query is executed.

c05.indd 74 12/6/12 1:28 AM Understanding the Loop ❘ 75

5. Once the content is retrieved, WordPress sets all of the is_ conditional tags such as is_home() and is_page(). These are set as part of executing the default query based on the URL parsing, and you’ll consider cases where you may need to reset these tags. 6. WordPress picks a template from your theme based on the type of query and the number of posts returned — for example, a single post or a category-only query — and the output of the query is passed to this default invocation of the Loop. The Loop can be customized for different website purposes. For example, a news site might use the Loop to display the latest news headlines. A business directory could use the Loop to display local businesses alphabetically by name, or always put posts about sponsoring businesses at the top of every displayed page. An e-commerce site might use the Loop to display products loaded into the website. The possibilities are endless when customizing the Loop in WordPress because it gives you complete control over what content is selected and the order in which it is rendered for display.

From Query Parameters to SQL Once the query parameters have been established, either by disassembling the URL provided by the reader or by having them explicitly set in a customized loop, the WP_Query object’s get_ posts() method translates those parameters into SQL for a database query. While you can exercise great control over the type, selection, and ordering of content through the query parameters, the WordPress core also exposes fi lters to allow you to change the generated SQL for even finer-grain control over content selection and grouping. The basic format of a SQL query is: SELECT fi elds FROM table WHERE conditions. “Fields” are the columns of the database that you want returned; you usually don’t need to modify this part of the query. The “conditions” specifi ed in the WHERE clause change the ordering, grouping, and number of posts returned. If you dump out the generated SQL query by examining the request fi eld of the WP_Query object, you’ll see that the WHERE portion of the SQL contains 1=1 as the fi rst conditional. If there are no other content selection parameters, the 1=1 ensures that the generated SQL isn’t syntactically malformed in the absence of other WHERE clauses; the SQL optimizer in MySQL knows enough to ignore the 1=1. “Table” is not simply the “posts” table in the MySQL database that contains all post data; it may also refer to an SQL JOIN of two or more tables where you need to select posts based on hierarchical metadata. WordPress makes it easy to put multiple tags on a post, or to put a post in more than one category, but relational databases aren’t adept at managing these hierarchical or networked relationships. As you see in Chapter 6, the WordPress data model uses multiple tables to manage these complex relationships, but that makes queries such as “fi nd all posts tagged bacon” more diffi cult to execute. For example, to select the posts tagged bacon, an SQL JOIN is needed to fi rst fi ndbacon in the metadata taxonomy, build an intermediate, in-memory table of posts that have been tagged with bacon, and then select posts whose IDs appear both in the intermediate table and the main WordPress content table. Database afi cionados call this a “Cartesian product” or inner join of two or more tables; the multiplicative description in both query complexity and memory consumption is accurate. In Chapter 8, you will dig into plugins and how they attach to fi lter and action hook insertion points in the WordPress core. Within the SQL request generation, there are a number of fi lters that are invoked to give plugin authors late-binding and very explicit control over the SQL that gets executed. For example, consider a plugin that changes the post selection based on custom post

c05.indd 75 12/6/12 1:28 AM 76 ❘ CHAPTER 5 THE LOOP

metadata and context that the plugin maintains in a separate database table. Your plugin would use the posts_join fi lter to rewrite the JOIN clause, adding another table and fi eld match clause to further expand the selection set. If you want to explore the core for the gory details of SQL generation, most of the query-to-request parsing is done in wp-includes/query.php, and the bulk of the JOIN work is set up in wp-includes/taxonomy.php. One fi nal note on SQL generation: WordPress does a very good job of building canonical URLs, that is, one and only one way to reference a particular post. Search engines notoriously consider http:// example.com/bacon and http://example.com/2012/bacon as distinct pages, even if they refer to the same piece of content (this is largely done to discourage more notorious practice of link farming where many distinct URLs are generated to feign the popularity of a single target). Part of the URL parsing function within the WordPress core attempts to clean up and redirect URLs to their canonical form; the same functions also make every effort to return some relevant content rather than a 404 page. As a result, if an attempt to load a page by name fails to return any content, WordPress will insert a LIKE modifi er into the WHERE clause that contains the post name. For example, if a user supplies the URL http://example.com/2012/scott, but you have no posts with the title “Scott,” the LIKE clause will match any posts that start with “Scott,” such as “Scott Gomez Finally Scored.” Canonical URLs and “like name” matching are part of the complex maze of URL rewriting and intent parsing that try to generate a pleasant user experience, rather than an annoying 404 error.

Understanding Content in WordPress Before diving into the Loop in detail, it’s important to understand the different types of content in WordPress. By default, WordPress defi nes two types of content: posts and pages. What you’ll see in Chapter 6 is that all content types are stored in the same MySQL table, and are differentiated by their “type.” Since the release of WordPress 2.9, it’s possible to defi ne your own custom post types, which is basically custom content in WordPress. For example, you could have an Events custom post type to register events in WordPress. Throughout this chapter, content is referred to as “posts,” but it’s important to remember that posts could really be any type of content in WordPress. Custom post types are covered in Chapter 7.

Putting the Loop in Context Header The Loop is the heart of a theme, which is what controls how your content is displayed. It is the functional connection between the MySQL database data and the HTML that is rendered in the visitor’s browser. Basically, anywhere a post or page is displayed, WordPress is going to use the Loop. This can be a single post or page, a loop of posts, or a sequence of loops with different Sidebar display options.

Most WordPress themes feature a header, footer, and sidebar The WordPress Loop element. Figure 5-1 shows how the Loop is placed directly in the middle of these elements, creating your website content area. Footer This section of your website is usually dynamic and will change as you navigate through it. FIGURE 5-1: The WordPress Loop

c05.indd 76 12/6/12 1:28 AM Understanding the Loop ❘ 77

The Loop, by default, is used in your WordPress theme template Header fi les. Custom Loops can be created anywhere in your theme template fi les, as Figure 5-2 shows. Custom Loops are also used in plugins and widgets. Loops can be used anywhere inside of WordPress, but different methods exist for creating custom Sidebar Loops depending on where they are used, and the potential side effects of each construction will differ. Multiple Loops can be used throughout your theme template fi les. Custom Loops can be created in your header, sidebars, footer, and main content areas of your website. There is no limit to the number of Loops that can be displayed on your website. Keep in mind that a Loop is effectively a database query to select Footer content and then an iteration over the selection to display it. The default Loop uses context from the visited URL to make that selection but you can fi ne-tune and craft a query against the WordPress content database to implement any number of content FIGURE 5-2: Using multiple Loops management processes. The following section looks at the basic fl ow control of the Loop and the WordPress template functions provided to customize the way content is displayed while being handled inside of a loop. Having armed you with the basics, you will now go into building custom Loops based on hand-tailoring those query parameters.

Flow of the Loop The Loop uses some standard programming conditional statements to determine what and how to display. The fi rst statement in the Loop is an if statement that checks whether any posts exist, because you might not have any posts with the specifi ed category or tag. If content exists, the while statement is used to initiate the Loop and cycle through all posts or pages that need to be displayed. Finally, the_post() function is called to build the post data, making it accessible to other WordPress functions. Once the post data has been built, Loop content can be displayed in whatever format you like. Following is a minimal Loop example. This example features the only required elements for the Loop to function properly:

Remember that this is PHP code, so it needs to be surrounded in tags. This is the Loop in its simplest form. If you’re wondering how the output from the database query got handed to this simple Loop when there are no variables passed as parameters, the answer lies in the global

c05.indd 77 12/6/12 1:28 AM 78 ❘ CHAPTER 5 THE LOOP

variable $wp_query, which is an instance of WP_Query that is referenced by the functions in the simple Loop. It is, in effect, the default query for the Loop. Note that by the time this default Loop is called, WordPress has already called the get_posts() method within the default query object to build the list of appropriate content for the URL being viewed, and the Loop in this case is charged with displaying that list of posts. Later on, you look at how to hand-structure queries to exercise fi ne-grain control over post selection, but for now it’s safe to assume that the database heavy lifting has been done, and the results are stored in $wp_query, when the Loop is invoked. Some very minimal requirements exist for the Loop to work in WordPress. Let’s break down this example to look at the different parts of the Loop: if ( have_posts() ) : This line checks if any posts or pages are going to be displayed on the current page you are viewing. If posts or pages exist, the next line will execute: while ( have_posts() ) :

The preceding while statement starts the Loop, essentially looping through all posts and pages to be displayed on the page until there are no more. The Loop will continue while content exists to be displayed. Once all content has been displayed, the while loop will end. The have_posts() function simply checks to see if the list of posts being processed is exhausted, or had no entries to begin with. the_post();

Next, the the_post() function is called to load all of the post data. This function must be called inside your loop for the post data to be set correctly. Calling the_post() in turn calls the setup_postdata() function to set up the per-post metadata such as the author and tags of the content you are displaying in the Loop, as well as the content of the post itself. This data is assigned to a global variable each time through the Loop iteration. Specifi cally calling the_post() has the side effect of setting up the global $post variable used by most of the template tags described later on, and then advances to the next post in the list. Setting up the post data also applies the appropriate fi lters to the raw content that comes out of the WordPress database. WordPress stores user-edited content exactly as entered, so if a user adds a shortcode, for example, to add a Google AdSense item at the end of a post, the shortcode is stored in the database content. When the post setup is done, the plugin that converts that shortcode to a chunk of JavaScript is called, along with other registered plugins that modify the raw post content. You’ll look at the plugin mechanics in Chapter 8, but for now, it’s important to note the distinction between the raw post data in the WordPress query object and the fi ltered content that is eventually rendered. //loop content This is where all Loop template tags are placed and any additional code you want displayed inside the Loop. This is covered in more detail further along in this chapter. endwhile; endif;

The endwhile and endif calls end the Loop. Any code placed after these two lines will show at the bottom of your page, after all posts have been displayed. You could also place an else clause to display a message if there is no content to display in the Loop.

c05.indd 78 12/6/12 1:28 AM Template Tags ❘ 79

The Loop is usually surrounded by HTML tags in your theme template fi les. The following code shows how the Loop is structured in the core Twenty Eleven theme that comes with WordPress:

Notice how the minimal Loop elements exist but are surrounded by HTML tags. This is how a normal theme template fi le will be structured to utilize the Loop. The HTML elements can certainly change, but the Loop elements stay the same. Customizing the style in which content is displayed and choosing post metadata to include in the page composition is done through template tags.

TEMPLATE TAGS

PHP functions used in your WordPress theme templates to display Loop content are called template tags. These tags are used to display specifi c pieces of data about your website and content. This allows you to customize how and where content is displayed on your website.

c05.indd 79 12/6/12 1:28 AM 80 ❘ CHAPTER 5 THE LOOP

For example, the the_title() template tag displays the title of your post or page inside the Loop. The major benefi t of using template tags is that you don’t need to know PHP code to use them. Many different template tags are available in WordPress. Some template tags must be inside the Loop, whereas other tags can be used anywhere in your theme template fi les. Note that in this context, template tags refer to the WordPress functions used to extract post data for display; template fi les are the theme elements that control how content for a particular content type is displayed. Put another way, template fi les contain Loops comprising template tags. For an updated list of template tags available in WordPress, visit http://codex.wordpress.org/Template_Tags.

Commonly Used Template Tags There is no shortage of template tags, but typically you will use only a handful of tags in your Loops. Following are the most commonly used template tags available in the Loop. These template tags will return and display the post data listed.

➤ the_permalink() — Displays the URL of your post. ➤ the_title() — Displays the title of the post. ➤ the_ID() — Displays the unique ID of your post. ➤ the_content() — Displays the full content of your post. ➤ the_excerpt() — Displays the excerpt of your post. If the Excerpt fi eld is fi lled out on the Post edit screen, that will be used. If not, WordPress will auto-generate a short excerpt from your post content. ➤ the_time() — Displays the date/time your post was published. ➤ the_author() — Displays the author of the post. ➤ the_tags() — Displays the tags attached to the post. ➤ the_category() — Displays the categories assigned to the post. ➤ edit_post_link() — Displays an edit link that is shown only if you are logged in and allowed to edit the post. ➤ comments_popup_link() — Displays a link to the comments form of your post. To learn how template tags work, just place any template tag inside the Loop and view the results. The following example views the values of a couple different template tags:

c05.indd 80 12/6/12 1:28 AM Customizing the Loop ❘ 81

As you can see, your post titles are displayed with links to the permalink for each post. The content of the post is displayed directly below the post title.

Tag Parameters Most template tags have parameters that can be added to modify the value returned. For example, the the_content() template tag has two parameters. The fi rst parameter allows you to set the more link text like so:

Your post content will be displayed as normal, but when the tag is found in your post, WordPress will automatically add the text Read more, which would link to the entire blog post. The second parameter determines whether to display the teaser paragraph again when viewing the full post. The default value is false so the teaser will be displayed in both places.

NOTE The more tag in WordPress allows you to display a defi ned teaser from the full post on your website. For example, you could display the fi rst paragraph of a post on your homepage, and only show the full blog post when a visitor clicks the link to view the full post. To accomplish this, you can place in your content in HTML view where you want this break to happen. In the visual editor, there is a button to insert a More tag.

You can also send multiple parameters to any template tag that supports it. For example, the template tag the_title() accepts three parameters: $before, $after, and $echo. The following code sets the the_title() tags $before and $after parameters to wrap the post title with h1 tags: ', '' ); ?> You can also view the actual function in the WordPress source code. The post template functions are located in wp-includes/post-template.php. Doing a quick search for function the_ title() will lead you to the exact function for the the_title() tag. You can also use the Codex for a detailed description of the template tag you are working with, in this case http://codex.wordpress.org/Template_Tags/the_title.

CUSTOMIZING THE LOOP

The opening discussion of Loop fl ow of control mentioned that the main workhorse for data selection is the get_posts() method of the WP_Query object. In most cases, if you want to build a custom Loop, you’ll build your own WP_Query object and reference it explicitly. Alternatively, you can use the lower-level query_posts() and get_posts() functions (not to be confused with the methods within the WP_Query object of the same name) to manipulate the output of the default query that was passed into your Loop. Both query_posts() and get_posts() use the WP_Query class to retrieve content. You’ll look at the lower level approaches and discuss how and where you should — and shouldn’t — use them, but you’ll start with a discussion of how you build a custom query object.

c05.indd 81 12/6/12 1:28 AM 82 ❘ CHAPTER 5 THE LOOP

Using the WP_Query Object Once WordPress is handed a URL to parse by the web server, it goes to work disassembling the tokens in that URL and converting them into parameters for a database query. Here’s a bit more detail on what happens when manipulating your own WP_Query.

WP_Query is a class defi ned in WordPress that makes it easy to create your own custom Loops. Both query_posts() and get_posts() use the WP_Query class to retrieve the WordPress content. When you’re using query_posts(), the global variable $wp_query is used as an instance of WP_Query, making $wp_query the default data store for several operations. Custom Loops can be used anywhere in your theme template fi les to display different types of content; they must build on separate instances of a WP_Query variable.

When you create a new WP_Query object, it’s instantiated with some default functions for building queries, executing the query to get posts, and parsing parameters out of a URL. However, you can use these built-in object methods to construct your own parameter strings, creating custom loops that extract whatever particular content you need for that point in your Loop. The following is an example of a custom Loop displaying the fi ve most recent posts on your website: have_posts() ) : $myPosts->the_post(); ?>

Rather than using the simpler have_posts() and the_post() calls that you saw in the basic Loop, this custom loop calls the methods of the newly created WP_Query object $myPosts. The explicit invocation shown here and the default have_posts() call are functionally equivalent; have_posts(), for example, is merely calling $wp_query->have_posts() using the global query variable for the default query — that is, the one generated from parsing the URL handed to WordPress by the web server. Going into your default Loop from the URL used to invoke WordPress; there’s an additional step that takes the URL and parses it into an appropriate query string using the parse_query() method of the query object. When you build your own custom Loop, you explicitly set the parameters you want to control the query. Here’s a bit more detail on what happens inside the query function:

➤ Calling $myPosts->query() converts the parameters into an SQL statement via the function $myPosts->get_posts(), which then executes the query against the MySQL database and extracts the content you’ve requested. ➤ Equally important, the query call sets up the conditional tags such as is_home() and is_ single() that are dependent upon the type of page displayed and the quantity of content for that page. ➤ The array of posts returned by the query is cached by WordPress so that future references to the same query won’t generate additional database traffi c. The key to building a powerful custom Loop is to map your content selection criteria into the right set of query parameters.

c05.indd 82 12/6/12 1:28 AM Customizing the Loop ❘ 83

Building a Custom Query Parameters are used to defi ne what content will be returned in your Loop, whether a custom Loop or altering the primary Loop. When creating Loops it’s essential to understand what parameters are available to help defi ne what content will be displayed. You can use many different, sometimes confusing, parameters in creating your custom Loop to alter the output of your content. Multiple parameters can also be set per query by separating the parameter name and values with an ampersand. For a detailed list of available parameters, visit http://codex.wordpress .org/Class_Reference/WP_Query#Parameters. The following sections cover some of the more commonly used parameters.

Post Parameters The most obvious, and sometimes most used parameters, select the number and types of posts to be displayed:

➤ p=2 — Loads an individual post by ID. ➤ name=my-slug — Loads post based on post slug (permalink tail). ➤ post_status=pending — Loads posts by post status. For example, if you choose to see only drafts, use post_status=draft. ➤ ignore_sticky_posts — Excludes sticky posts from being returned fi rst. A sticky post is one that always sorts to the top of the list of posts, independent of the other parameters set for the query. You can have multiple sticky posts, making them useful for calling attention to news announcements, highlighting changes, or otherwise grabbing reader’s attention, and this parameter lets you drop them from their priority slot at the top of the list. ➤ post_type=page — Loads posts based on type. If you only want to look at pages, not posts, post_type=page will retrieve them. This parameter enables special-purpose loops to select content based on custom post types, as you’ll see in Chapter 7. ➤ posts_per_page=5 — Number of posts to load per page. This is the default. To show all posts, set this parameter to –1. ➤ offset=1 — Number of posts to skip before loading.

Page Parameters Pages have parameters similar to those for posts to control their selection:

➤ page_id=5 — Loads an individual page by ID. Like post IDs and user IDs, page IDs can be found in the dashboard by hovering over a page and looking at the URL displayed at the bottom on your browser. ➤ pagename=Contact — Loads a page by name, in this case the Contact page. ➤ pagename=parent/child — Loads a child page by slug, or hierarchy of slugs (that is, its path).

c05.indd 83 12/6/12 1:28 AM 84 ❘ CHAPTER 5 THE LOOP

Category, Tag, and Author Parameters Posts can also be sorted by the category into which they were placed, by tags applied to the post, or by author information:

➤ cat=3,4,5 — Load posts based on category ID. ➤ category_name=About Us — Loads posts based on category name. Note that if a post belongs to more than one category, it will show up in selections for each of those categories. ➤ tag=writing — Loads posts based on tag name. ➤ tag_id=34 — Loads posts based on tag ID. ➤ author=1 — Loads posts based on author ID. ➤ author_name=brad — Loads posts based on author’s name.

Time, Date, Ordering, and Custom Parameters Parameters to select content based on their chronology are a key part of building an archive of posts, or providing a view into content through a calendar on your blog’s homepage. You can also change the sort parameter and the sort order. If you’re building an online index, and want to show an alphabetical post listing, you’ll set the parameters for querying posts by month and author, but order the results by title.

➤ monthnum=6 — Loads posts created in June. ➤ day=9 — Loads posts created on the 9th day of the month. ➤ year=2012 — Loads posts created in 2012. ➤ orderby=title — Field to order posts by. ➤ order=ASC — Defi nes ascending or descending order of orderby. ➤ meta_key=color — Loads posts by custom fi eld name. Refer to the custom taxonomy and data discussion in Chapter 7 to see how custom fi elds are added to posts. ➤ meta_value=blue — Loads posts by custom fi eld value. Must be used in conjunction with the meta_key parameter above.

Putting It Together Now look at some examples using parameters. The following examples use the $myPosts- >query() function from the $myPosts custom query object created in the example to select the content displayed in your custom Loop. Display post based on post ID: $myPosts = new WP_Query( 'p=1' ); Display the fi ve latest posts, skipping the fi rst post: $myPosts = new WP_Query( 'posts_per_page=5&offset=1' );

c05.indd 84 12/6/12 1:28 AM Customizing the Loop ❘ 85

Display all posts from today: // display all posts from the current date $today = getdate(); // get todays date $myPosts = new WP_Query('year=' .$today["year"] .'&monthnum=' .$today["mon"] .'&day=' .$today["mday"] ); Display all posts from October 31, 2013: $myPosts = new WP_Query( 'monthnum=10&day=31&year=2013' );

Display all posts from category ID 5 with the bacon tag: $myPosts = new WP_Query( 'cat=5&tag=bacon' );

Display all posts with the bacon tag, excluding posts in category ID 5: $myPosts = new WP_Query( 'cat=-5&tag=bacon' );

Display all posts with the tag writing or reading: $myPosts = new WP_Query( 'tag=writing,reading' );

Display all posts with the tags writing and reading and tv: $myPosts = new WP_Query( 'tag=writing+reading+tv' );

Display all posts with a custom fi eld named color with a value of blue: $myPosts = new WP_Query( 'meta_key=color&meta_value=blue' ); Adding Paging to a Loop If your custom Loop requires paging (navigation links), you will need to take a few extra steps. Paging is currently designed to work only with the $wp_query global variable; that is, it works within the default Loop and requires some sleight of hand to make it work in custom Loops. You need to trick WordPress into thinking your custom query is actually $wp_query in order for paging to work. have_posts() ) : $wp_query->the_post(); ?>

First, you have to store the original $wp_query variable into the temporary variable $temp. Next, you set $wp_query to null to completely fl ush it clean. This is one of the few times it’s acceptable to overwrite a global variable value in WordPress. Now set your new WP_Query object into the $wp_query variable and execute it by calling the object’s query() function to select posts for your custom Loop. Notice the $paged variable added to the end of the query. This stores the current

c05.indd 85 12/6/12 1:28 AM 86 ❘ CHAPTER 5 THE LOOP

page, using the get_query_var() function, so WordPress knows how to display the navigation links. Now display your navigation links for paging:

Finally, you need to reset $wp_query back to its original value: Now your custom Loop will contain proper pagination based on the content returned.

Using query_posts( ) A tremendous amount of customization can be done by specifying the appropriate set of parameters for your Loop. While the WP_Query object is the most general-purpose mechanism for extracting content from the WordPress database, there are other lower-level methods that you’ll encounter.

The query_posts() function is used to easily modify the content returned for the default WordPress Loop. Specifi cally, you can modify the content returned in $wp_query after the default database query has executed, fi ne-tune the query parameters, and re-execute the query using query_posts(). The downside to calling query_posts() in this fashion is that the previously cached results from the default query are discarded, so you’re incurring a database performance hit to use this shortcut. The query_posts() function should be placed directly above the start of the Loop: query_posts( 'posts_per_page=5&paged='.$paged ); if ( have_posts() ) : while ( have_posts() ) : the_post(); //loop content (template tags, html, etc) endwhile; endif; This example tells WordPress to display only fi ve posts.

Explicitly calling query_posts() overwrites the original post content extracted for the Loop. This means any content you were expecting to be returned before using query_posts() will not be returned. For example, if the URL passed to WordPress is for a category page at http://example .com/category/zombie/, none of the zombie category posts will be in the post list after query_ posts() has been called unless one is in the fi ve most recent posts. You explicitly overwrite the query parameters established by the URL parsing and default processing when you pass the query string to query_posts(). To avoid losing your original Loop content, you can save the parsed query parameters by using the $query_string global variable: // initialize the global query_string variable global $query_string;

// keep original Loop content and change the sort order query_posts( $query_string . “&orderby=title&order=ASC” );

c05.indd 86 12/6/12 1:28 AM Customizing the Loop ❘ 87

In the preceding example, you would still see all of your zombie category posts, but they would be ordered alphabetically by ascending title. This technique is used to modify the original Loop content without losing that original content.

You can also pack all of your query_posts() parameters in an array, making it easier to manage. Following is an example of how to retrieve only the sticky post set in WordPress using an array called $args to store the parameter values: $args = array( 'posts_per_page' => 1, 'post__in' => get_option( 'sticky_posts' ) ); query_posts( $args );

If no sticky post is found, the latest post will be returned instead. The query_posts() function is used to modify the main page Loop only. It is not intended to create additional custom Loops. If you want to make a slight change to the default query — for example, adding posts of a specifi c category or tag to every displayed page — then the query_posts() approach is a shortcut. However, it’s not without side effects or cautions:

➤ query_posts() modifi es the global variable $wp_query and has other side effects. It should not be called more than once and shouldn’t be used inside the Loop. The example shows the call to query_posts() before post processing has started, when the extra parameters are added to the query string but before the Loop has begun to step through the returned post list. Calling query_posts() more than once, or inside the Loop itself, can result in your main Loop being incorrect and displaying unintended content. ➤ query_posts() unsets the global $wp_query object, and in doing so, may invalidate the values of conditional tags such as is_page() or is_home(). Going through the entire WP_Query object instantiation sets all of the conditional tags appropriately. For example, you may fi nd with the shortcut that you have added content to a selection that the default query found contained only one post, and therefore is_single() is no longer valid. ➤ Calling query_posts() executes another database query, invalidating all of the cached results from the fi rst, default query. You at least double the number of database queries executed and are incurring a performance hit for each trip back to MySQL; on the other hand the default query has already been run by the time you get to the default Loop, so there’s little chance to work around it if you’re building an entirely custom main Loop. Using get_posts( ) Like query_posts(), there’s an alternative, simpler access function called get_posts() that retrieves raw post data. You’ll see get_posts() used in administration pages to generate a list of pages of a particular type, or it may be used within a plugin to grab all raw data for a set of posts and examine it for patterns such as common terms, tags, or external links, with the intent of discarding the content after a quick digestion. It’s not intended for user-facing content display because it turns off much of query processing and fi ltering that is done within the more general WP_Query approach.

What get_posts() lacks, specifi cally, is the ability to set up all of the global data needed to make template tags refl ect the current post data. One main issue is that not all template tags are available

c05.indd 87 12/6/12 1:28 AM 88 ❘ CHAPTER 5 THE LOOP

to get_posts() by default. To fi x this defi ciency, you need to call the setup_postdata() function to populate the template tags for use in your Loop. The following example shows how to retrieve a single random post using get_posts():

$randompost = get_posts( 'numberposts=1&orderby=rand' ); foreach( $randompost as $post ) : setup_postdata( $post ); ?>

You’ll notice another major difference using get_posts() — the value returned is an array. The foreach loop code is used to cycle through the array values. This example returns only one post, but if more than one were returned, this would cycle through each. Then the setup_post- data() function is called to populate the data for your template tags.

Remember that you can also set up your get_posts() parameter using an array: 1, 'orderby' => rand );

$randompost = get_posts( $args );

Although you may see older code using get_posts() or query_posts() constructions, WP_Query is the preferred approach and should be the heart of custom loop syntax. However, there are times when you’ll want the quick-and-dirty access provided by get_posts() to generate additional context or data for further customization of your Loop or in a plugin.

Resetting a Query When customizing the main Loop, or creating custom Loops, it’s a good idea to reset the Loop data after you are done. WordPress features two different functions to handle this: wp_reset_postdata() and wp_reset_query().

The fi rst method for resetting post data is wp_reset_data(). This function actually restores the global $post variable to the current post in the main query. This is the preferred method when using WP_Query to create custom Loops.

For example, assume you have the following custom Loop in your theme’s header.php fi le:

// The Loop while ( $myPosts->have_posts() ) : $myPosts->the_post(); ?>

c05.indd 88 12/6/12 1:28 AM Customizing the Loop ❘ 89

This will display a random post in the header of your theme. This code will also change the main query object for other Loops on the page. The original query data will not be available, which could produce unexpected results on the main posts Loop for your theme.

To fi x the problem, place a call to wp_reset_postdata() directly after your custom Loop like so: $myPosts = new WP_Query( 'posts_per_page=1&orderby=rand' );

// The Loop while ( $myPosts->have_posts() ) : $myPosts->the_post(); ?>

// Reset Post Data wp_reset_postdata();

Calling this function will restore the $post variable to the current post in the query. This will eliminate any strangeness in the main query for the page you are viewing.

The second method available for resetting post data is the wp_reset_query() function. From time to time, you may run into problems with page-level conditional tags being used after a custom Loop has been created. Conditional tags allow you to run different code on different pages in WordPress, for example, using the conditional tag is_home() to determine if you are viewing the main blog page. This problem is caused, as indicated in the, “Using query_posts( )” section, by potentially changing the output of a database query after setting the conditional tags based on its original set of values. To fi x this issue, you need to call wp_reset_query(). This function will properly restore the original query, including the conditional tags set up early in the URL parsing process. Consider the following example:

Executing this code will return the latest fi ve posts followed by the links saved in your WordPress link manager. The problem you will run into is that the is_home() conditional tag will not be interpreted correctly, meaning your links will show on every page, not just the homepage. To fi x this issue, you need to include wp_reset_query() directly below your Loop:

c05.indd 89 12/6/12 1:28 AM 90 ❘ CHAPTER 5 THE LOOP

if( is_home() && !is_paged() ): wp_list_bookmarks( 'title_li=&categorize=0' ); endif; ?>

Now that you have properly restored your Loop’s instance of the WP_Query object, the conditional tag is_home() will be followed and your links will now display only on the homepage of your website. It’s a good practice to add wp_reset_query() after using query_posts() in your Loop to ensure you do not run into problems down the road. The wp_reset_query() function actually calls wp_reset_postdata(), but it does one additional step. The function actually destroys the previous query before resetting it. In short, wp_reset_query() should always be used after a query_posts() Loop and wp_reset_postdata() should be used after a WP_Query or get_posts() custom Loop.

More Than One Loop The Loop can be used multiple times throughout your theme and plugins. This makes it easy to display different types of content in multiple places throughout your WordPress website. Maybe you want to display your most recent blog posts below each page on your website. You can achieve this by creating more complex Loops that make multiple passes through the list of posts, or by generating multiple post arrays over which to loop.

Nested Loops Nested Loops can be created inside your theme templates using a combination of the main Loop and separate WP_Query instances. For example, you can create a nested Loop to display related posts based on post tags. The following is an example of creating a nested Loop inside the main Loop to display related posts based on tags:

//loop content (template tags, html, etc) ?>

$tags = wp_get_post_terms( get_the_ID() ); if ( $tags ) {

echo 'Related Posts';

$tagcount = count( $tags ); for ( $i = 0; $i < $tagcount; $i++ ) { $tagIDs[$i] = $tags[$i]->term_id; }

$args=array(

c05.indd 90 12/6/12 1:28 AM Customizing the Loop ❘ 91

'tag__in' => $tagIDs, 'post__not_in' => array( $post->ID ), 'posts_per_page' => 5, 'ignore_sticky_posts' => 1 ); $relatedPosts = new WP_Query( $args ); if( $relatedPosts->have_posts() ) { //loop through related posts based on the tag while ( $relatedPosts->have_posts() ) : $relatedPosts->the_post(); ?>

} endwhile; endif; ?> This code will display all of your posts as normal. Inside the main Loop, you check if any other posts contain any of the same tags as your main post. If so, you display the latest fi ve posts that match as related posts. If no posts match, the related posts section will not be displayed.

Multi-Pass Loops The rewind_posts() function is used to reset the post query and loop counter, allowing you to do another Loop using the same content as the fi rst Loop. Place this function call directly after you fi nish your fi rst Loop. Here’s an example that processes the main Loop content twice:

Advanced Queries You can also perform more advanced queries in your Loops. Now construct a Loop that will compare a custom fi eld value using the meta_compare parameter: $args = array( 'posts_per_page' => '-1', 'post_type' => 'product', 'meta_key' => 'price', 'meta_value' => '13', 'meta_compare' => '<='

c05.indd 91 12/6/12 1:28 AM 92 ❘ CHAPTER 5 THE LOOP

);

$myProducts = new WP_Query( $args );

// The Loop while ( $myProducts->have_posts() ) : $myProducts->the_post(); ?>

// Reset Post Data wp_reset_postdata();

As you can see, the meta_compare parameter is used to display all products with a meta value for price that is less than or equal to (<=) 13. The meta_compare parameter can accept all sorts of comparison operators such as !=, >, >=, <, <=, and the default, which is =.

For more complex meta data queries, you’ll use the meta_query parameter. Now you can expand upon the preceding example. Instead of just returning product entries that are less than or equal to a price of 13, you can also only return products that are the color blue: $args = array( 'post_type' => 'product', 'meta_query' => array( array( 'key' => 'color', 'value' => 'blue', 'compare' => '=' ), array( 'key' => 'price', 'value' => '13', 'type' => 'numeric', 'compare' => '<=' ) ) );

$myProducts = new WP_Query( $args );

// The Loop while ( $myProducts->have_posts() ) : $myProducts->the_post(); ?>

// Reset Post Data wp_reset_postdata();

Notice the meta_query parameter accepts an array of parameters. In this example, the fi rst item in the array is an array to verify the products are blue. The second parameter is an array to verify the product price is less than or equal to 13. Creating Loops using meta query parameters can be extremely powerful. This is an important tool for creating complex websites with various meta data options.

c05.indd 92 12/6/12 1:28 AM Global Variables ❘ 93

GLOBAL VARIABLES

A global variable is a variable that has a defi ned value that can be accessed anywhere within the WordPress execution environment. These variables store all types of information about the Loop content, author, and users, and specifi c information about the WordPress installation such as how to connect to the MySQL database. Global variables should only be used to retrieve data, meaning you should never write data to these variables directly. Overwriting the global variable values could cause unexpected results in WordPress because signifi cant parts of core and extended functionality depend on these values being set within one context and remaining consistent for the duration of a query, page load, or single-post handling. Assigning values to global variables almost always has unintended side effects, and they’re almost always not what the user or blog author wanted. However, global variables are discussed here to shed more light on how post data can be manipulated, and you may see code snippets that utilize these functions for post processing outside of the Loop.

Post Data You saw how the key fi rst step in the Loop is calling the_post(). Once invoked, you will have access to all of the data in WordPress specifi c to the post being displayed. This data is stored in the global $post variable. The $post variable stores the post data of the last post displayed on the page. So if your Loop displays ten posts, the $post variable will store post data for the tenth post displayed.

The following example shows how you can reference the $post global variable and display all values in the array using the print_r() PHP function.

The preceding code will print the array values for the $post global variable. The default WordPress blog post would look like this: stdClass Object ( [ID] => 1 [post_author] => 1 [post_date] => 2012-06-09 19:05:19 [post_date_gmt] => 2012-06-09 17:23:50 [post_content] => Welcome to WordPress. This is your first post. Edit or delete it, then start blogging! [post_title] => Hello world! [post_excerpt] => [post_status] => publish [comment_status] => open [ping_status] => open [post_password] => [post_name] => hello-world [to_ping] => [pinged] =>

c05.indd 93 12/6/12 1:28 AM 94 ❘ CHAPTER 5 THE LOOP

[post_modified] => 2012-06-09 19:04:12 [post_modified_gmt] => 2012-06-09 19:04:12 [post_content_filtered] => [post_parent] => 0 [guid] => http://localhost/Brad/?p=1 [menu_order] => 0 [post_type] => post [post_mime_type] => [comment_count] => 1 [ancestors] => Array ( )

[filter] => raw )

As you can see, the $post global variable contains all sorts of data for the post. You can also display specifi c pieces of data from the array, such as the post title and content like so: post_title; //display the post title echo $post->post_content; //display the post content ?>

Accessing the content through the global $post variable means that you are accessing the unfi ltered content. This means any plugins that would normally alter the output of the content will not affect the global content value. For example, if you had the built-in [gallery] shortcode in your post to display all images uploaded on the post, retrieving the post content as shown would return [gallery] instead of the actual image gallery. Remember that WordPress provides template tags that can be called anywhere to retrieve these values as well, and in most cases, template tags are going to be the preferred mechanism for getting at these bits. For example, if you need to get the permalink of your post, you can use the following method: ID ); //displays the posts permalink ?> This is covered in more detail in the section, “Working Outside the Loop,” later in this chapter.

Author Data $authordata is a global variable that stores information about the author of the post being displayed. You can use this global variable to display the author’s name: display_name; ?>

c05.indd 94 12/6/12 1:28 AM Global Variables ❘ 95

The $authordata variable is created when setup_postdata() is called during the_post() function call in the Loop. This means the $authordata global variable will not be created until the Loop has run for the fi rst time. Another problem with this method is that the global values do not get passed through hook fi lters, meaning that any plugin you install to override this functionality would not be run. The preferred method for accessing the author metadata, like that for getting post data, is to use the available WordPress template tags. For example, to display the author’s display name, you would use this code:

The get_the_author_meta() and the_author_meta() functions are available for retrieving all metadata related to the author of the content. If this template tag is used inside the Loop, there is no need to pass the user ID parameter. If used outside of the Loop, the user ID is required to determine what author metadata to retrieve.

User Data The $current_user global variable stores information on the currently logged-in user. This is the account that you are currently logged in to WordPress with. Following is an example showing how to display the logged-in user’s display name: display_name; ?> This is a useful technique if you want to display a welcome message to your users. Remember that the display name will default to the user’s username. To display a welcome message to any user that is logged in, you could use this code: display_name ) { echo 'Welcome ' .$current_user->display_name; } ?> Environmental Data WordPress also has global variables created for browser detection. The following is an example showing how you can detect the user’s browser version in WordPress using global variables:

if ( $is_lynx ) { echo "You are using Lynx"; }elseif ( $is_gecko ) { echo "You are using Firefox";

c05.indd 95 12/6/12 1:28 AM 96 ❘ CHAPTER 5 THE LOOP

}elseif ( $is_IE ) { echo "You are using Internet Explorer"; }elseif ( $is_opera ) { echo "You are using Opera"; }elseif ( $is_NS4 ) { echo "You are using Netscape"; }elseif ( $is_safari ) { echo "You are using Safari"; }elseif ( $is_chrome ) { echo "You are using Chrome"; }elseif ( $is_iphone ) { echo "You are using an iPhone"; } ?> This is extremely useful when designing a website that needs to include browser-specifi c tasks or functionality. As always, it’s best to stick with web standards and degrade gracefully for lesser browsers, but in some circumstances this can be very benefi cial. For example, you can use the $is_iphone variable to load a custom style sheet for iPhone web users. WordPress features another global variable to detect if the user is on a mobile device, which could be a smartphone or tablet. This global variable is called $is_mobile. Rather than calling this global variable directly, there’s a handy function available called wp_is_mobile(). This function detects if the user is on a mobile device. If you are browsing using a mobile device, the function returns true; if not, the function returns false, as shown here: if ( wp_is_mobile() ) { echo "You are viewing this website on a mobile device"; }else{ echo "You are not on a mobile device"; }

WordPress also stores what type of web server the website is hosted on using the $is_IIS and $is_apache global variables. Here’s an example: Depending what web server a website is using, code can produce different results than expected. As a developer, you need to consider that your plugins and themes may be running on WordPress installations on different web servers; you might also need to check what the user is running in order to accomplish specifi c tasks.

Global Variables or Template Tags? Generally speaking, template tags should be used whenever they can be. There will be certain instances where a template tag will not be available. In this case, global variables can be substituted to access the information you need. Also, global variables are great for retrieving unfi ltered data,

c05.indd 96 12/6/12 1:28 AM Working Outside the Loop ❘ 97

meaning the values will bypass any plugin, altering what would normally be used against the content and giving you the original value to work with. Once your code has accessed or processed the original value, you can still force the plugin fi lters to run using the following code: post_content );?> While this is included in a discussion of working outside of the Loop, you can access these global variables inside the loop, but again remember to treat globals as read-only, as changing their values will have possibly negative side effects.

WORKING OUTSIDE THE LOOP

There are times when you’ll want to access generic post information, or to manipulate some information about the currently displayed post outside of the Loop. WordPress provides some functions to operate on sets of posts for even fi ner-grain control over post display. Along with access to global variables, there is a set of WordPress functions to return generic information that’s not specifi c to a single post, or the post currently displayed. Following is a list of frequently used functions when working outside the Loop:

➤ wp_list_pages() — Displays a list of pages as links ➤ wp_list_categories() — Displays a list of categories as links ➤ wp_list_bookmarks() — Displays links saved in the Links SubPanel ➤ wp_tag_cloud() — Displays a tag cloud from all tags ➤ get_permalink() — Returns the permalink of a post ➤ next_posts_link() — Link to display previous posts ➤ previous_posts_link() — Link to display next posts You already saw how you could create navigational links using next_posts_link() and previous_posts_link() in the custom Loop example. Now explore some of these functions to get a real feel for how they work.

To display a list of pages in WordPress, you can use the wp_list_pages() function. This function will return your pages in a list format, so it’s important to wrap the function call with

About

c05.indd 97 12/6/12 1:28 AM 98 ❘ CHAPTER 5 THE LOOP

Order
Contact

You can also use the wp_page_menu() function to generate a page menu. There are several advantages to this page listing function. The fi rst is a new show_home parameter allowing a Home link to automatically be added to the list of pages. You also don’t have to remove the title using title_li as done in the preceding code. This function also wraps a custom

around your menu, the class of which you can set. The following is an example of this function:

Another common function for generating links is wp_list_categories(). This function lists your categories, and subcategories, in a list as well. Consider the following example:

This code will generate a list of categories with links. As before, you are setting your title to nothing, rather than the default Categories title. You are also setting the depth to 4. The depth parameter controls how many levels in the hierarchy of categories to be included in the list. The categories will be ordered by their name. You are also excluding three categories (8, 16, and 34) based on their IDs.

The functions next_posts_link() and previous_posts_link() are typically used directly after your Loop has completed. These two functions will generate the previous and next links for viewing more posts on your website. Notice that the next_posts_link() function actually returns your previous posts. The reason for this is that WordPress assumes your posts are displaying in reverse chronological order, meaning the next page of posts would actually be posts from earlier in the timeline. Now imagine you’d like to load a single post outside of the Loop. To do this, you use the get_post() function to load your post data. The following example loads the post data for post ID 1031: post_title .'
'; echo 'Post Content: ' .$myPost->post_content .'
'; ?>

The get_post() function has only one required parameter: the post ID you want to load. You must pass a variable containing an integer for the ID. Passing a literal integer (for example, 5) will cause a fatal error. The second optional parameter is how you would like the results returned: as an object, an associative array, or a numeric array. By default, an object is returned. To return an associative array you can run this code:

c05.indd 98 12/6/12 1:28 AM Working Outside the Loop ❘ 99

'; echo 'Post Content: ' .$myPost['post_content'] .'
'; ?>

No matter how you return the results, however, this invocation of get_post() returns the raw content from the WordPress database. Filters and processing normally done within the loop won’t be applied to the returned content. The solution is to use the setup_postdata() function in conjunction with get_post() to set up your global post data and template tags for use with your post:

The get_post() function uses the internal WordPress object cache. This means that if the post you are loading is already in the cache you will avoid running an unneeded database query. It’s easy to see how useful this function can be to quickly and effi ciently load a single post outside of the Loop. Some functions that can be used inside the Loop can also be used outside of the Loop. For example, you can use the the_author_meta() function to retrieve specifi c author metadata: The email address for user id 1 is

Remember that when calling the the_author_meta() function outside of the Loop, you have to specify the author’s ID that you want to load metadata for. If you call this function inside the Loop, you do not need to specify this ID because it will load the author data for the current post. WordPress also features specifi c functions for retrieving individual data about a post outside of the Loop. For example, you can use the get_the_title() function to retrieve a post’s title based on post ID like so: You can also use a function to retrieve post metadata (custom fi elds) from an individual post. To do this, you use the get_post_meta() function, as shown here:

The get_post_meta() function accepts three parameters: post ID, key, and single. The post ID is the ID of the post you want to load metadata for. The key is the name of the meta value you want to load. The third optional value determines whether the results are returned as an array or whether the function will return a single result. By default, this is set to false so an array would be returned. As you can see, you can set this value to true so only a single color is returned.

c05.indd 99 12/6/12 1:28 AM 100 ❘ CHAPTER 5 THE LOOP

SUMMARY

This chapter covered the basic mechanics of WordPress content selection and display and provided a guide to the WordPress core to help you locate the code used to implement these functions. The real power of WordPress is in its extensibility through plugins and themes. You are fi rst going to look at the WordPress data model in more detail in Chapter 6, showing you how the various data items saved for all content, users, and metadata relate to each other. Chapter 7 will cover custom post types, custom taxonomies, and metadata showing you the various types of content you can defi ne and use in WordPress. You will then use that as the basis for a full-fl edged plugin construction discussion in Chapter 8. Along with plugins, themes are the other primary avenue for extending and customizing WordPress, and you reapply some of the Loop constructs with a deeper look at templates and content presentation in Chapter 9.

c05.indd 100 12/6/12 1:28 AM 6 Data Management

WHAT’S IN THIS CHAPTER?

➤ Understanding the WordPress database ➤ Learning about database table relationships ➤ Working with the WordPress database class ➤ Debugging custom queries

Almost every website on the Internet today is connected to a database that stores information about that website. WordPress is no different and is powered by a MySQL database back end. This database stores all of the data for your website, including your content, users, links, metadata, settings, and more. This chapter covers how data is stored, what data is stored, and how to work with that data in WordPress to help you build amazing websites.

DATABASE SCHEMA

The default installation of WordPress contains 11 database tables. WordPress prides itself on being very lightweight and the database is the foundation for this. The database structure is designed to be very minimal yet allow for endless fl exibility when developing and designing for WordPress. To understand the database schema, it helps to view a database diagram. Figure 6-1 shows an overview of the WordPress database structure and the tables created during a standard WordPress installation. Keep in mind that plugins and themes have the ability to create custom tables. WordPress Multisite also creates additional tables so your WordPress database may contain more tables than just the default WordPress tables.

c06.indd 101 12/6/12 1:29 AM 102 ❘ CHAPTER 6 DATA MANAGEMENT

FIGURE 6-1: WordPress database diagram

When a new major release of WordPress is launched, a few database changes are usually made. These changes are usually very minor, such as changing a table fi eld data type or removing a fi eld that is no longer in use. Backward compatibility is a major focus for the WordPress development community so any changes made to the database are highly scrutinized and will rarely affect active plugins and themes. The Codex features a very thorough database changelog you can reference when a new version of WordPress is released: http://codex.wordpress.org/ Database_Description#Changelog. The table structure in WordPress is very consistent. Each table in your database contains a unique ID fi eld, which is the primary key of the table. Each table also contains one or more indexes on fi elds, which improves the speed of data retrieval when executing queries against the data. As you saw in Chapter 5, each trip through the Loop in a theme is going to generate at least one, and perhaps several, queries to extract posts, pages, and their related metadata or comments.

c06.indd 102 12/6/12 1:29 AM Table Details ❘ 103

The most important fi eld in every table is the unique ID fi eld. This fi eld is not always named ID, but is an auto-incrementing fi eld used to give each record in the table a unique identifi er. For example, when you fi rst install WordPress, a default post is created titled “Hello world!” Because this is the fi rst post created in thewp_posts table, the ID for this post is 1. Each post is given a unique ID that can be used to load post-specifi c information and can also be used as the joining fi eld against other tables in the database. There is one caveat to this, and that is post revisions, attachments, and custom post types. Each one of these entries is saved as a new record in the wp_posts table so they each get their own unique ID, which means your published post IDs may not be sequential. For example, your fi rst post may have an ID of 1, whereas your second post may have an ID of 15. It all depends on how many additional entries have been created between each post.

TABLE DETAILS

Currently, 11 database tables have been created for WordPress. Following is a list of those tables and details on what data they store:

➤ wp_commentmeta — Contains all metadata for comments. ➤ wp_comments — Contains all comments within WordPress. Individual comments are linked back to posts through a post ID. ➤ wp_links — Contains all links added via the Link Manager section. ➤ wp_options — Stores all website options defi ned under the Settings SubPanel. Also stores plugin options, active plugins and themes, and more. ➤ wp_postmeta — Contains all post metadata (custom fi elds). ➤ wp_posts — Contains posts of all types (default and custom post types), pages, media records, and revisions. Under most circumstances, this is the largest table in the database. ➤ wp_terms — Contains all taxonomy terms defi ned for your website, mapping their text descriptions to term numbers that can be used as unique indexes into other tables. ➤ wp_term_relationships — Joins taxonomy terms with content, providing a membership table. It maps a term such as a tag or category name to the page or post that references it. ➤ wp_term_taxonomy — Defi nes the taxonomy to which each term is assigned. This table allows you to have categories and tags with the same name, placing them in different named taxonomies. ➤ wp_users — Contains all users created in your website (login, password, e-mail). ➤ wp_usermeta — Contains metadata for users (fi rst/last name, nickname, user level, and so on).

Each database table has a specifi c purpose within WordPress. The next section breaks down some of the more common tables and looks at some examples of working with each.

c06.indd 103 12/6/12 1:29 AM 104 ❘ CHAPTER 6 DATA MANAGEMENT

WordPress Content Tables To retrieve all of your website content, you’ll be accessing the wp_posts table. This table stores all of your posts, pages, attachments, and revisions. Attachment records are stored in this table, but the actual attachments are not. They are physically stored on your hosting server as a standard fi le. The following SQL query is an example of how to extract all of your posts from the database, and is the short form of what happens in the default WordPress Loop:

SELECT * FROM wp_posts WHERE post_type = 'post' AND post_status = 'publish' ORDER BY post_date DESC

This query selects all records from wp_posts with a post_type of 'post'. The post_type fi eld designates what type of content you are viewing. To return all pages, just change that value to 'page'. In this example, you want published posts only, so make sure post_status is set to 'publish'. You are also ordering your table records by post_date descending, so your posts will be displayed in reverse chronological order. Querying data and what tools are available to help you do so are discussed later in this chapter.

Let’s explore some of the more useful fi elds in the wp_posts table. You already know your ID fi eld contains your post’s unique ID. The post_author fi eld is the unique ID of the author of the post. You can use this to retrieve author-specifi c data from thewp_users table. The post_date is the date the post was created. The post_content fi eld stores the main content of your post or page and post_title is the title of that content.

One very important fi eld is the post_status fi eld. Currently, seven different post statuses are defi ned in WordPress:

1. publish — A published post or page. 2. inherit — A post revision. 3. pending — Post that is pending review by an administrator or editor. 4. private — A private post. 5. future — A post scheduled to publish at a future date and time. 6. draft — A post still being created and is a draft. 7. trash — Content is in the trash bin and can still be recovered.

Post status comes into play when contributor roles are used to limit a post creator’s ability to post or edit existing content. The use of roles is discussed in Chapter 12, and their impact on content management workfl ow is discussed in Chapter 14. As with almost everything in WordPress, custom post statuses can be created by plugins and themes.

The post_type is also stored in this table. This value is what distinguishes different types of content in WordPress: posts, pages, revisions, and attachments. Since the release of WordPress 2.9, custom post types can be created, which opens the door to endless possibilities when defi ning custom content in WordPress.

c06.indd 104 12/6/12 1:29 AM Table Details ❘ 105

The wp_users table contains data for your registered member accounts. Again, you see the ID fi eld indicating the unique identifi er for user records. The user_login is the username of the user. This is the value the user must enter when logging in to WordPress. The user_pass fi eld contains the phpass encrypted user password. The registered user’s e-mail is stored in the user_email fi eld. The user_url fi eld contains the member’s website and the user registration date is saved in user_registered.

Next you will explore the wp_comments table. This table stores all of the comments, pingbacks, and trackbacks for your website.

Viewing the comment records, you’ll notice the ID fi eld is named comment_ID. Even though this fi eld is not named ID, it is still the unique identifi er for this record in the table. The comment_post_ ID is the unique ID of the post the comment was added to. Remember that by default you don’t have to be logged in to make comments in WordPress. For this reason, you’ll see similar fi elds as in your users table.

The comment_author fi eld stores the name of the commenter. If the comment is a pingback or trackback, it will contain the name of the post that sent the ping. The comment_author_email contains the commenter’s e-mail address, and his or her website is stored in comment_author_url. Another important fi eld is the comment_date, which is the date the comment was created. This fi eld is used to display your post comments in the correct order.

WordPress Taxonomy Tables Terms, relationships, and taxonomies are broken into three distinct tables to allow many-to-one relationships between categories, tags, items in custom taxonomies, and posts. These relationships are hierarchical and multi-valued. While you could add an array of tag or category identifi ers to each row in the wp_posts table, for example, that approach puts an explicit limit on the number of descriptive relationships for each post while also wasting space allocated for tags or categories that may not be assigned. If you create a category called “cured ham,” and put four posts in that category, all three taxonomy- related tables are updated:

1. One row in the wp_terms table defi nes “cured ham” and its slug, or diminutive form used in URLs. This relationship gets a unique identifi er (key) useful for matching the term to other tables. 2. One row in the wp_term_taxonomy table maps “cured ham” to the “category” taxonomy. This relationship also gets a unique key, representing the combination of “cured ham” in “category.” If you also create a custom taxonomy and have a “cured ham” entry in it, there will be a different row in the wp_term_taxonomy table for that mapping, along with its unique key. 3. Four rows in the wp_term_relationships table map the “cured ham in category” identifi er to the post identifi ers for each of the posts that are in the category.

The workhorse operator in working with taxonomy tables is the SQL JOIN, sometimes referred to as the “product” of two (or more) tables. A JOIN builds a temporary table with each row in one

c06.indd 105 12/6/12 1:29 AM 106 ❘ CHAPTER 6 DATA MANAGEMENT

table mapped to every row in the second and successive tables; then the WHERE part of a JOIN operation selects those rows where specifi c fi elds in each row match. To fi nd all of the posts in the “cured ham” category, WordPress fi rst fi nds the identifi er for this term and taxonomy pair, selects the appropriate rows from the wp_term_relationships table, and then does a JOIN on the wp_posts and the selected rows from the relationships table: that last JOIN is SQL-ese for “extract all of the posts with identifi ers in this list” where the list is computed on-the-fl y.

Figure 6-2 shows a graphical representation of the joins between the wp_posts table and taxonomy tables in WordPress.

FIGURE 6-2: Taxonomy tables relationship

While this makes the SQL for selecting content associated with a particular tag or category more complex, requiring the use of a multi-table JOIN operations to implement the “name in a taxonomy in a relationship” matching, it is powerful in allowing content to be given rich and multi-valued descriptions, and for category, taxonomy, and tag names to have independent name spaces.

WORDPRESS DATABASE CLASS

WordPress features an object class with method functions for working with the database directly. This database class is called wpdb and is located in wp-includes/wp-db.php. Any time you are querying the WordPress database in PHP code, you should use the wpdb class. The main reason for using this class is to allow WordPress to execute your queries in the safest way possible.

Simple Database Queries When using the wpdb class, you must fi rst defi ne $wpdb as a global variable before it will be available for use. To do so, just drop this line of code directly preceding any $wpdb function call:

global $wpdb;

One of the most important functions in the wpdb class is the prepare() function. This function is used for escaping variables passed to your SQL queries. This is a critical step in preventing SQL injection attacks on your website. All queries should be passed through the prepare function before being executed. Here’s an example:

c06.indd 106 12/6/12 1:29 AM WordPress Database Class ❘ 107

query( $wpdb->prepare( "INSERT INTO $wpdb->my_custom_table ( id, field_key, field_value ) VALUES ( %d, %s, %s )", 1, $field_key, $field_value ) );

This example adds data into a non-default, custom table in WordPress that you would have previously created. When using prepare(), make sure to replace any variables in your query with %s for strings and %d for integers. Then list the variables as parameters for the prepare() function in the exact same order. In the preceding example, %d represents 1, %s represents $field_key, and the second %s represents $field_value. The prepare function is used on all queries from here on out.

Notice that this example uses $wpdb->my_custom_table to reference the table in WordPress. This translates to wp_my_custom_table if wp_ is the table prefi x. This is the proper way to determine the correct table prefi x when working with tables in the WordPress database.

NOTE When installing WordPress, you can set a custom database table prefi x. By default, this is wp_, but many people choose to change this prefi x for security purposes. Using $wpdb-> is the correct way to determine what this table prefi x is for any WordPress installation.

The wpdb query() method is used to execute a simple query. This function is primarily used for SELECT and DELETE statements. Despite its name, it’s not only for SQL SELECT queries, but will execute any SQL statement against the database. Here’s a basic query function example:

query( $wpdb->prepare( " DELETE FROM $wpdb->my_custom_table WHERE id = '1' AND field_key = 'address' " ) );

As you can see, you execute your query using the wpdb class query() function to delete the field "address" with an ID of 1. Although the query() function allows you to execute any SQL query on the WordPress database, other database object class functions are more appropriate for SELECT queries. For instance, the get_var() function is used for retrieving a single variable from the database:

get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->comments;" ) ); echo '

Total comments: ' . $comment_count . '

'; ?>

c06.indd 107 12/6/12 1:29 AM 108 ❘ CHAPTER 6 DATA MANAGEMENT

This example retrieves a count of all comments in WordPress and displays the total number. Although only one scalar variable is returned, the entire result set of the query is cached. It’s best to try and limit the result set returned from your queries using a WHERE clause to only retrieve the records you actually need. In this example, all comment record rows are returned, even though you display the total count of comments. This would obviously be a big memory hit on larger websites.

Complex Database Operations To retrieve an entire table row, you’ll want to use the get_row() function. The get_row() function can return the row data as an object, an associative array, or a numerically indexed array. By default, the row is returned as an object, in this case an instance of the per-post data. Here’s an example:

get_row( $wpdb->prepare( "SELECT * FROM $wpdb->posts WHERE ID = 1" ) ); echo $thepost->post_title; ?>

This retrieves the entire row data for post ID 1 and displays the post title. The properties of $thepost object are the column names from the table you queried, which is wp_posts in this case. To retrieve the results as an array, you can send in an additional parameter to the get_row() function:

get_row( $wpdb->prepare( "SELECT * FROM $wpdb->posts WHERE ID = 1" ), ARRAY_A ); print_r ( $thepost ); ?>

By using the ARRAY_A parameter in get_row(), your post data is returned as an associative array. Alternatively, you could use the ARRAY_N parameter to return your post data in a numerically indexed array.

Standard SELECT queries should use the get_results() function for retrieving multiple rows of data from the database. The following function returns the SQL result data as an array:

get_results( $wpdb->prepare( "SELECT ID, post_title FROM $wpdb->posts WHERE post_status = 'publish' " ) );

foreach ( $liveposts as $livepost ) { echo '

' .$livepost->post_title. '

'; } ?>

The preceding example is querying all published posts in WordPress and displaying the post titles. The query results are returned and stored as an array in $liveposts, which you can then loop through to display your query values.

The WordPress database class also features specifi c functions for UPDATE and INSERT statements. These two functions eliminate the need for custom SQL queries because WordPress will create

c06.indd 108 12/6/12 1:29 AM WordPress Database Class ❘ 109

them for you based on the values passed into the function. Here is how the insert() function is structured:

$wpdb->insert( $table, $data );

The $table variable is the name of the table you want to insert a value into. The $data variable is an array of fi eld names and data to be inserted into those fi eld names. So, for example, if you want to insert data into a custom table, you would execute this:

insert( $wpdb->my_custom_table, array( 'field_one' => $newvalueone, 'field_two' => $newvaluetwo ) );

The fi rst thing you do is set two variables to store the data you want to insert. Next, you execute the insert() function, passing in both variables through an array. Notice how you set field_one and field_two as the two fi elds you are inserting. You can pass any fi eld available in the table you are inserting with data to insert into that fi eld.

The update() function works very similarly to the insert() function, except you also need to set the WHERE clause variable so WordPress knows which records to update:

$wpdb->update( $table, $data, $where );

The $where variable is an array of fi eld names and data for the SQL WHERE clause. This is normally set to the unique ID of the fi eld you are updating, but can also contain other fi eld names from the table.

update( $wpdb->posts, array( 'post_title' => $newtitle, 'post_content' => $newcontent ), array( 'ID' => $my_id ) ); ?>

First you set your updated title and content variables. You also set the variable $my_id, which contains the ID of the post you want to update. Next, you execute the update() function. Notice that the third parameter you send is an array containing your WHERE clause values, in this case the post ID. The preceding query updates the title and content for post ID 1. Remember that you can send multiple values through the WHERE parameter when updating a table record.

The insert() and update() functions shown do not need to be wrapped with the prepare() function. Both of these functions actually use the prepare() function after concatenating the query from the values passed to the functions. This is a much easier method than manually creating your INSERT and UPDATE queries in WordPress.

c06.indd 109 12/6/12 1:29 AM 110 ❘ CHAPTER 6 DATA MANAGEMENT

Dealing with Errors Any time you are working with queries, it’s nice to see error messages. By default, if a custom query fails, nothing is returned so it’s hard to determine what is wrong with your query. The wpdb class provides functions for displaying MySQL errors to the page. Here’s an example of using these functions:

show_errors(); $liveposts = $wpdb->get_results( $wpdb->prepare("SELECT ID, post_title FROM $wpdb->posts_FAKE WHERE post_status = 'publish'") ); $wpdb->print_error(); ?>

The show_errors() function must be called directly before you execute a query. The print_ error() function must be called directly after you execute a query. If there are any errors in your SQL statement, the error messages are displayed. You can also call the $wpdb->hide_errors() function to hide all MySQL errors, or call the $wpdb->flush() function to delete the cached query results. The database class contains additional variables that store information about WordPress queries. Following is a list of some of the more common variables:

var_dump( $wpdb->num_queries ); // total number of queries ran var_dump( $wpdb->num_rows ); // total number of rows returned by the last query var_dump( $wpdb->last_result ); // most recent query results var_dump( $wpdb->last_query ); // most recent query executed var_dump( $wpdb->col_info ); // column information for the most recent query

Add the preceding code directly after you execute a query to see the results. This is very useful when determining why a database query isn’t working as expected.

Another very powerful database variable is the $queries variable. This stores all of the queries run by WordPress. To enable this variable, you must fi rst set the constant valueSAVEQUERIES to true in your wp-config.php fi le. This tells WordPress to store all of the queries executed on each page load in the $queries variable. First drop this line of code in your wp-config.php fi le:

define( 'SAVEQUERIES', true );

Now all queries will be stored in the $queries variable. You can display all of the query information like so:

var_dump( $wpdb->queries ); // displays all queries executed during page load

This is especially handy when troubleshooting slow load times. If a plugin is executing an obscene number of queries, that can dramatically slow down load times in WordPress. Remember to disable the SAVEQUERIES constant option when you are fi nished viewing queries because storing all queries can also slow down load times.

c06.indd 110 12/6/12 1:29 AM Direct Database Manipulation ❘ 111

The database query class is a major asset when working with the WordPress database directly, as you will see when developing a plugin or building a more complex Loop. All of the previously mentioned database class functions use specifi c escaping techniques to verify that your queries are executed in the safest manner possible. To borrow from Randall Munroe’s “Little Bobby Tables” xkcd joke (xkcd #327), you don’t want a user handcrafting an input item that contains DROP TABLES as a malicious SQL injection, resulting in the loss of your WordPress database tables. The query preparation and escaping functions ensure that inputs don’t become SQL functions, no matter how craftily they’re set up. It is essential that you follow these methods for querying data to ensure your website is the most effi cient and uses the safest techniques possible.

DIRECT DATABASE MANIPULATION

There may be times when you want to work with the WordPress database data directly. This can include accessing custom database tables created by a plugin or theme. To do this, you’ll need to use SQL to query the data from the MySQL database. Remember that the WordPress APIs provide access to all of the WordPress tables and only very occasionally will you need to access the tables directly. All example queries in this chapter use the wp_ prefi x for tables, but your database tables may use a different prefi x as defi ned in your wp-config.php fi le when installing WordPress. One of the most common methods for working with a WordPress database directly is by using php- MyAdmin, shown in Figure 6-3. As described in Chapter 3, phpMyAdmin is a free software tool provided by most hosting companies for administering MySQL databases through a web interface. Most of the examples in this section involve direct interaction with MySQL, and you’ll need to use an SQL command line for their execution. Figure 6-3 shows the default database view using phpMyAdmin.

FIGURE 6-3: phpMyAdmin viewing a WordPress database

To run SQL statements in phpMyAdmin simply click the SQL tab across the top. Here you can execute any queries against your WordPress database. We always recommend creating your query directly in phpMyAdmin fi rst before moving it over to your PHP scripts. The reasoning behind this is that debugging SQL statements is much faster directly in phpMyAdmin than it is using PHP code in WordPress. Once you have perfected your query, you can use it in your PHP code and you can

c06.indd 111 12/6/12 1:29 AM 112 ❘ CHAPTER 6 DATA MANAGEMENT

be confi dent the results will be as expected. In the examples that follow you’ll be using raw SQL queries. Remember that if you want to run these queries in a theme or plugin, you’ll need to wrap the queries in the WordPress database class.

One of the most commonly accessed tables is the wp_posts table. Remember that this table stores all posts, pages, custom post types, revisions, and even attachment records. The different types of content are defi ned by the post_type fi eld. WordPress 2.9 introduced the ability for developers to defi ne custom post types, which is discussed in greater detail in Chapter 7. This means that additional post_type values may exist in this fi eld. To view all post revisions in your database, you can run this query:

SELECT * FROM wp_posts WHERE post_type = 'revision'

This returns all records in wp_posts that are of a revision post_type. You can modify the preceding query to view all post attachments that have been uploaded to WordPress:

SELECT guid, wp_posts.* FROM wp_posts WHERE post_type = 'attachment'

This example places the fi eld guid as the fi rst value to be returned in the query. The guid fi eld contains the full URL of the attachment fi le on the server.

The wp_options table contains all of the settings saved for your WordPress installation. Options saved in this table are saved with an option_name and option_value. Therefore, the actual fi eld name you call will always be those two names, rather than a specifi c fi eld based on the option value. Following are two extremely important records in this table:

SELECT * FROM wp_options WHERE option_name IN ( 'siteurl','home' )

This query returns two records, one where option_name is home and another where option_name is siteurl. These are the two settings that tell WordPress what the domain of your website is. If you ever need to change your website’s domain, you can run a query to update these two values like so:

UPDATE wp_options SET option_value = 'http://yournewdomain.com' WHERE option_name IN ('siteurl','home')

Once this query runs, your website will instantly run under the new domain. Remember that this only updates the website’s domain in WordPress. Attachment URLs in posts and pages will also need to be updated to point to the new domain. Plugins can also store the domain information, so be sure to test in a development environment before updating a production website. If you access the old domain, you will be redirected to the new one. If you were logged in, your cookies and session will be invalidated and you will have to log in again. This is a great technique if you built a new website under a subdomain (for example, http://new.example.com) and are updating the URLs to push the website live.

c06.indd 112 12/6/12 1:29 AM Direct Database Manipulation ❘ 113

The wp_options table contains other very important fi elds. To view all active plugins on your website, you can view the active_plugins option_name like so:

SELECT * FROM wp_options WHERE option_name = 'active_plugins'

The options table also stores all options defi ned by plugins. Most plugins activated in WordPress will have some type of settings page. These settings are generally saved in wp_options so the plugins can retrieve these settings as needed. For example, the Akismet plugin stores an option named akismet_spam_count that stores the total number of spam comments. You can view this option by running the following query:

SELECT * FROM wp_options WHERE option_name = 'akismet_spam_count'

The wp_users table contains all of the users you currently have set up in WordPress. If you allow open registration on your website, new users will be created in this table as they join your site. The wp_users table stores very important user information including username, password, e-mail, website URL, and date registered. Say you want to export all of your users’ e-mail addresses. You can easily do so by running the following query:

SELECT DISTINCT user_email FROM wp_users

Now you can easily export all of the e-mail addresses loaded into WordPress! Another common query used in wp_users is to reset a user’s password. You can do this in a couple of different ways, but if you are absolutely locked out of WordPress, you can always reset the password directly in the database. To do so, you need to update the user_pass fi eld from the MySQL command line:

UPDATE wp_users SET user_pass = MD5('Hall0w33n') WHERE user_login ='admin' LIMIT 1;

Running this query resets the admin password to Hall0w33n. Notice how you wrap the new password in MD5(). This converts the password to an MD5 hash. Since WordPress 2.5, passwords are now salted and hashed using the phpass encryption library rather than MD5. Not to worry, however, because WordPress is built to detect MD5 hash passwords and convert them to phpass encryption instead. So the preceding query will successfully reset your password in WordPress.

The wp_comments table stores all comments submitted to your website. This table contains the comment, author, e-mail, website URL, IP address, and more. Here’s an example query for displaying comments:

SELECT wc.* FROM wp_posts wp INNER JOIN wp_comments wc ON wp.ID = wc.comment_post_ID WHERE wp.ID = '1554'

c06.indd 113 12/6/12 1:29 AM 114 ❘ CHAPTER 6 DATA MANAGEMENT

This query returns all comments for post ID 1554. Another important fi eld in wp_comments is the user_id fi eld. If a user is logged in to your website and posts a comment, this fi eld will contain his or her user ID. Consider the following code, which displays all comments left by the user admin:

SELECT wc.* FROM wp_comments wc INNER JOIN wp_users wu ON wc.user_id = wu.ID WHERE wu.user_login = 'admin'

In the database diagram in Figure 6-1, the arrows show the relationships between each table. This is incredibly useful when writing custom queries to retrieve data directly from the database. For example, to retrieve all comments for a particular post you could run this query:

SELECT * FROM wp_comments INNER JOIN wp_posts ON wp_comments.comment_post_id = wp_posts.ID WHERE wp_posts.ID = '1'

This query returns all comments for post ID 1. Notice how you join the wp_comments.comment_ post_ID fi eld to the wp_posts.ID fi eld. The SQL JOIN is necessary because there is an N:1 relationship between comments and posts; each post may have many comments but comments apply to only one post. These two fi elds are shown in the diagram as the joining fi elds for these tables. Also consider the following example, which demonstrates how to join the wp_users and wp_usermeta tables together:

SELECT * FROM wp_users INNER JOIN wp_usermeta ON wp_users.ID = wp_usermeta.user_id WHERE wp_users.ID = '1'

As you can see in the database diagram, the wp_users.ID fi eld was joined to the wp_usermeta .user_id fi eld. The preceding query retrieves all of the user information, including user metadata, for user ID 1, which is the default admin account. Again, the database diagram makes it extremely easy to determine how tables are joined by index value inside the WordPress database, and how logical INNER JOIN operations can build result sets of related table rows. If you are interested in learning more about SQL, you can read some amazing tutorials at http://www.w3schools.com/sql/default.asp.

SUMMARY

This chapter covered the WordPress database schema, database table relationships, the WordPress database class, and the proper way to debug database queries. Whether working with themes, plugins, or custom functions, understanding how to work with the WordPress database is very important. Understanding where and how WordPress stores data in the database can help as you develop more complex website features. Next you’ll cover custom content in WordPress using custom post types. You’ll also cover custom taxonomies, custom metadata, and the power and importance of both when developing WordPress websites.

c06.indd 114 12/6/12 1:29 AM 7 Custom Post Types, Custom Taxonomies, and Metadata

WHAT’S IN THIS CHAPTER?

➤ Understanding and creating custom post types ➤ Displaying and using custom post type content ➤ Creating and using custom taxonomies ➤ Understanding and using metadata

The most important part of any WordPress website is the content. WordPress, by default, has various types of content and taxonomies defi ned, but often, you will need to defi ne your own types of content to build the exact website you want. Over the past few years, WordPress has introduced some very advanced, and easy-to-use, tools for working with all sorts of custom content. This has helped WordPress evolve into a full- fl edged content management system capable of powering absolutely any type of website setup, regardless of the content. In this chapter, you learn how to create custom post types and content in WordPress. You also learn how to work with custom taxonomies to group and classify your content. Finally, you learn how to attach and retrieve arbitrary pieces of metadata to your content.

UNDERSTANDING DATA IN WORDPRESS

When working with various types of data in WordPress, it’s important to understand what that data is and how it can be customized. WordPress has fi ve predefi ned post types in a default installation: 1. Post — Blog posts or articles generally ordered by date 2. Page — Hierarchical static pages of content

c07.indd 115 12/6/12 1:31 AM 116 ❘ CHAPTER 7 CUSTOM POST TYPES, CUSTOM TAXONOMIES, AND METADATA

3. Attachment — Media uploaded to WordPress and attached to post type entries, such as images and fi les 4. Revision — A revision of a post type used as backup and can be restored if needed 5. Nav Menus — Menu items added to a nav menu using WordPress’ menu management feature For a basic blog or smaller website, these default post types are all you might need. However, if you plan on building a more complex CMS-type website, you’ll want to utilize the power of custom post types.

What Is a Custom Post Type? A custom post type in WordPress is a custom defi ned piece of content. Using custom post types, you can defi ne any type of content in WordPress, and you are no longer forced to use just the default post types listed in the previous section. This opens to door to an endless number of possibilities. Potential custom post type ideas include, but are not necessarily limited to, the following: ➤ Products ➤ Events ➤ Videos ➤ Rotator ➤ Testimonials ➤ Quotes ➤ Error Log Remember that custom post types can be absolutely anything, not just public-facing pieces of content. For example, you can set up a custom post type as an error log to track errors in your application. When it comes to custom post types, the only limitation is your imagination.

Register Custom Post Types To create a new custom post type, you’ll use the register_post_type() function as shown here: The register_post_type() function accepts two parameters: 1. $post_type — The name of the post type. Should contain only lowercase letters, no spaces, and a max length of 20 characters. 2. $args — An array of arguments that defi ne the post type and various options in WordPress. Now look at a basic example of registering a custom post type. You can register a post type in WordPress in two different places. The fi rst is in your theme’s functions.php fi le. The second is in a custom plugin. You could add the following code to a custom plugin, but for this example, add the following code to your theme’s functions.php fi le.

c07.indd 116 12/6/12 1:31 AM Understanding Data in WordPress ❘ 117

function prowp_register_my_post_types() {

register_post_type( 'products', array( 'labels' => array( 'name' => 'Products' ), 'public' => true, ) );

} ?>

Now visit your WordPress admin dashboard. You’ll notice that a new menu called Products has appeared just below Comments, as shown in Figure 7-1. That is the new custom post type you just registered with the preceding code. As you can see, WordPress will automatically create the admin UI for your new custom post type. The new menu item allows you to create new post type FIGURE 7-1: Products product entries as well as edit existing entries, just like posts and pages in custom post type WordPress. This is a basic example, but you can already tell the ease with which you can defi ne custom content in WordPress.

NOTE You should always use the init action hook when registering your custom post types. This is the fi rst hook available after WordPress is fully initialized and will verify that your custom post type is registered early enough in the process.

There are many different arguments available when registering your custom post type. It’s important to understand these arguments to know what’s available.

public Sets whether a post type is publicly available on the admin dashboard or front-end of your website. By default, this is set to false, which will hide the post type from view. The default settings for show_ui, exclude_from_search, publicly_queryable, and show_in_nav_menus are inherited from this setting.

show_ui This determines whether or not to create a default UI in the WordPress admin dashboard for managing this post type. It defaults to the value defi ned by the public argument.

publicly_queryable This determines if the post type content can be publicly queried on the front end of your website. If it is set to false, all front end queries for entries under the custom post type will return a 404, since it is not allowed to be queried. It defaults to the value defi ned by the public argument.

c07.indd 117 12/6/12 1:31 AM 118 ❘ CHAPTER 7 CUSTOM POST TYPES, CUSTOM TAXONOMIES, AND METADATA

exclude_from_search This allows you to exclude custom post type entries from the WordPress search results. It defaults to the value defi ned by the public argument.

show_in_nav_menus This determines if the post type is available for selection in the menu management feature of WordPress. It defaults to the value defi ned by the public argument.

supports This argument allows you to defi ne what meta boxes appear on the screen when creating or editing a new post type entry. This defaults to the title and editor. Several options are available:

➤ title — Sets the post title. ➤ editor — Displays the content editor on the post editing screen with a media uploader. ➤ author — Selects box to choose the author of the post. ➤ thumbnail — Featured image meta box for the post. ➤ excerpt — Displays an excerpt editor on the post type editing screen. ➤ comments — Sets whether comments will be enabled for posts of this type. ➤ trackbacks — Sets whether trackbacks and pingbacks will be enabled for posts of this type. ➤ custom-fields — Displays the custom fi eld editing area meta box. ➤ page-attributes — Displays the attributes box for choosing the post order. The hierarchical argument must be set to true for this to work. ➤ revisions — Displays the post revisions meta box. ➤ post-formats — Displays the post formats meta box with registered post formats.

labels This sets an array of labels that represents your post type in the admin dashboard. See the section, “Setting Post Type Labels,” later in this chapter for details on each label.

hierarchical The hierarchical argument allows you to defi ne if the post type is hierarchical, like pages in WordPress. A hierarchical post type allows you to have a tree-like structure for your post type content. By default, this argument is set to false.

has_archive This enables your post type to have an archive page. A post type archive page is like the WordPress posts page, which displays the site’s latest blog entries. This allows you to display a list of your post type entries, with the order being defi ned in your theme’s template file.

c07.indd 118 12/6/12 1:31 AM Understanding Data in WordPress ❘ 119

can_export This determines if the post type content is available for export using the built-in WordPress export feature under Tools ➪ Export. This argument is set to true by default.

taxonomies This names an array of registered taxonomies to attach to the custom post type. For example, you can pass in category and post_tag to attach the default Categories and Tags taxonomies to your post type. By default, there are no taxonomies attached to a custom post type.

menu_position This enables you to set the position in which the custom post type menu shows in the admin menu. By default, new post types are displayed after the Comments menu.

menu_icon This sets a custom menu icon for your post type. By default, the posts icon is used.

show_in_menu This determines whether or not to display the admin menu for your post type. This argument accepts three values: true, false, or a string. The string can be either a top-level page, such as tools.php, or edit.php?post_type=page. You can also set the string to the menu_slug parameter to add the custom post type as a submenu item to an existing custom menu. It defaults to the value defi ned by the show_ui argument.

show_in_admin_bar This sets whether or not to show your custom post type in the WordPress admin bar. It defaults to the value defi ned by the show_in_menu argument.

capability_type This names a string or an array of the capabilities for this post type. By default, the value is set to post.

capabilities This is an array of custom capabilities required for editing, deleting, viewing, and publishing posts of this post type.

query_var This argument sets the query variable for posts of this post type. The default value is true and is set to the $post_type value.

c07.indd 119 12/6/12 1:31 AM 120 ❘ CHAPTER 7 CUSTOM POST TYPES, CUSTOM TAXONOMIES, AND METADATA

rewrite The rewrite argument creates the unique permalinks for this post type. This allows you to customize the post type slug in your URL. This argument can be set to true, false, or an array of values. If passing an array, it accepts the following values:

➤ slug — Sets a custom permalink slug. Defaults to the $post_type value. ➤ with_front — Sets whether your post type should use the front base from your permalink settings. For example, if you prefi xed your permalinks with /blog, and with_front is set to true, your post type permalinks would include /blog at the beginning. ➤ pages — Sets whether the permalink provides for pagination. Defaults to true. ➤ feeds — Sets whether a feed permalink will be built for this post type. Defaults to has_archive value. By default this argument is set to true and the $post_type is used as the slug. This section has covered a lot of custom post type arguments. The following example puts some of the more common arguments to use.

function prowp_register_my_post_types() {

$args = array( 'public' => true, 'has_archive' => true, 'taxonomies' => array( 'category' ), 'rewrite' => array( 'slug' => 'product' ), 'supports' => array( 'title', 'editor', 'author', 'thumbnail', 'comments' ) );

register_post_type( 'products', $args );

} ?>

In this example, you fi rst set the post type to be public. You also enabled the post type to have an archive page by setting the has_archive argument to true. Using the taxonomies argument, you attached the default Category taxonomy to your product’s custom post type.

In this example, you want to change the permalink slug for your post type. Instead of http:// example.com/products/zombie-bait, using the default slug products from the post type name, you want to set your post type slug to the singular product. This will generate your permalink as http://example.com/product/zombie-bait. This is done using the rewrite argument and defi ning a custom slug for your post type. The fi nal argument you set is supports. The code adds the title, editor, author, featured image, and comments meta box to your custom post type create and edit screens.

c07.indd 120 12/6/12 1:31 AM Understanding Data in WordPress ❘ 121

NOTE When registering a new custom post type, it’s important to fl ush the rewrite rules in WordPress. You can do this by calling the function flush_ rewrite_rules() in your plugin’s activation hook or manually by going to Settings ➪ Permalinks and saving your permalink settings. This will eliminate 404 errors on your new post type permalinks.

To learn more about the register_post_type() function, visit the offi cial Codex page at http:// codex.wordpress.org/Function_Reference/register_post_type.

Setting Post Type Labels When creating a custom post type in WordPress, several text strings are shown throughout the WordPress admin dashboard for your post type. These text strings are typically a link, button, or extra information about the post type. By default, the term “post” is used for non-hierarchical post types and “page” for hierarchical post types. For example, when you use the basic custom post type registration code earlier in this chapter, you’ll notice the text “Add New Post” at the top of the page when you add a new Product. The reason for this is Product is a post of type Product. This isn’t very accurate, as you aren’t actually adding a post, but rather a new Product. Setting the labels argument when registering your custom post type will allow you to defi ne exactly what is shown. The available labels for your custom post types include:

➤ name — General name for the post type, which is usually plural. Used in the WordPress admin and by other plugins and themes. ➤ singular_name — The singular version of the name for the post type. It is also used in the WordPress admin and by other plugins and themes. ➤ add_new — The label for the Add New submenu item. The text defaults to “Add New.” ➤ add_new_item — Used as the header text on the main post listing page to add a new post. By default, the text is “Add New Post/Page.” ➤ edit_item — Used as the text for editing an individual post. Defaults to “Edit Post/Page.” ➤ new_item — Text for creating a new post. By default, it is set to “New Post/Page.” ➤ view_item — The text for viewing an single post entry. Defaults to “View Post/Page.” ➤ search_items — Text displayed for searching the posts of this type. It defaults to “Search Posts/Pages.” ➤ not_found — The text shown when no posts were found in a search. By default, it displays “No posts/pages found.” ➤ not_found_in_trash — The text shown when no posts are in the trash. Defaults to “No posts/pages found in Trash.” ➤ parent_item_colon — Text shown when displaying a post’s parent. This text is only used with hierarchical post types and displays “Parent Page:” by default.

c07.indd 121 12/6/12 1:31 AM 122 ❘ CHAPTER 7 CUSTOM POST TYPES, CUSTOM TAXONOMIES, AND METADATA

Setting each value makes for a much better user experience when administering a WordPress website. In the following code, you’ve modifi ed your original custom post type registration code and set the labels for the Product post type:

function prowp_register_my_post_types() {

$labels = array( 'name' => 'Products', 'singular_name' => 'Product', 'add_new' => 'Add New Product', 'add_new_item' => 'Add New Product', 'edit_item' => 'Edit Product', 'new_item' => 'New Product', 'all_items' => 'All Products', 'view_item' => 'View Product', 'search_items' => 'Search Products', 'not_found' => 'No products found', 'not_found_in_trash' => 'No products found in Trash', 'parent_item_colon' => '', 'menu_name' => 'Products' );

$args = array( 'labels' => $labels, 'public' => true );

register_post_type( 'products', $args );

} ?>

Working with Custom Post Types Now that you understand how to register a custom post type, let’s explore how you use them in your WordPress website. Typically it’s the job of your theme to display posts on the front end of your site. However, that may not always be the case as certain custom post types may not need to be publicly displayed — for example, an error log. It all depends on what the function of your post type is.

To display custom post type data, you can use the WP_Query custom Loop example from Chapter 5. Remember that WP_Query accepts a post_type parameter that determines what type of content to return. In the example that follows, you’ll return all of your product entries in WordPress:

$args = array( 'posts_per_page' => '-1', 'post_type' => 'products',

c07.indd 122 12/6/12 1:31 AM Understanding Data in WordPress ❘ 123

);

$myProducts = new WP_Query( $args );

// The Loop while ( $myProducts->have_posts() ) : $myProducts->the_post(); ?>

// Reset Post Data wp_reset_postdata();

Notice the post_type parameter is set to products, which is the $post_type parameter value used when you registered the Products custom post type. Now modify the custom Loop to return only products in the Specials category:

$args = array( 'posts_per_page' => '-1', 'post_type' => 'products', 'tax_query' => array( array( 'taxonomy' => 'category', 'field' => 'slug', 'terms' => 'specials' ) ) );

$myProducts = new WP_Query( $args );

Using the tax_query parameter in WP_Query, the custom Loop will return only product post type entries assigned to the Specials category.

You can use all of the same methods for creating custom Loops with WP_Query, as covered in detail in Chapter 5, to display your custom post type content. It’s easy to see the power custom post types bring to WordPress when developing more complex websites.

Custom Post Type Template Files Earlier in the chapter you learned about the has_archive argument when registering a custom post type. Enabling this argument will allow you to create an archive template fi le that will display all of your custom post type entries by default. The archive template for a custom post type must be named in the form of archive-{post-type}.php. For example, an archive template for your Products custom post type would be named archive-products.php. This archive template is a perfect place to display all of your products. Just like the archive template, WordPress will also recognize a single template for your post type entries. This is the template that is loaded when you visit a single entry for your custom post type.

c07.indd 123 12/6/12 1:31 AM 124 ❘ CHAPTER 7 CUSTOM POST TYPES, CUSTOM TAXONOMIES, AND METADATA

The single template must be named in the form of single-{posttype}.php. So your products single template would be named single-products.php. When visiting a single product URL, such as http://example.com/products/zombie-bait, the single-products.php template would load. Theme template fi les, including custom post types, are covered in more detail in Chapter 9.

Special Post Type Functions WordPress features many different post type–specifi c functions to make working with custom post types that much easier. In this section, you will review some of the more common functions you might use when building your websites.

To return a list of all registered post types in WordPress, you’ll use the get_post_types() function.

This function accepts three optional parameters: 1. $args — An array of arguments to match against the post type. 2. $output — The type of output to return, either names or objects. Defaults to names. 3. $operator — Operator to use with multiple $args. Defaults to and. Using the get_post_types() function, use the following to return a list of all custom post types registered in WordPress:

$args = array( 'public' => true, '_builtin' => false );

$post_types = get_post_types( $args, 'names', 'and' );

foreach ( $post_types as $post_type ) { echo '

'. $post_type. '

'; }

As shown in the preceding code, you’ll set two arguments in the $args array: public and _ builtin. The public argument will only return custom post types that are set to be publicly viewable. The _builtin argument is set to false, which will not return default post types like posts and pages. You also set the $output argument to return just the post type name, and the $operator argument to use “and” for the multiple $args you passed to the function.

To determine what post type a piece of content is, you’ll use the get_post_type() function:

This function accepts only one parameter — $post — which is a post object or a post ID.

c07.indd 124 12/6/12 1:31 AM Understanding Data in WordPress ❘ 125

You can display the post type of a post using the following code:

ID ); ?>

There may be a time when you want to work with a custom post type that was created by a plugin or theme. The fi rst thing you should always do is to verify that the custom post type you are looking for exists. To do so, you’ll use the post_type_exists() function.

The function accepts a single required parameter — $post_type — which is the post type you want to verify has been registered.

If you wanted to verify the products custom post type exists, you use this code:

if( post_type_exists( 'products' ) ) { echo 'The Products post type exists'; }

Another useful function when working with other custom post types is add_post_type_support(). This function allows you to register support for certain features on a post type, such as the featured image meta box.

This is a useful function if the existing post type doesn’t have support for a feature that you need. The add_post_type_support() function accepts two parameters: 1. $post_type — The post type name you are adding support to 2. $supports — A string or array of features to add As an example, assume the products post type does not support featured images or comments. To add support for both of these features, use the following code example:

add_post_type_support( 'products', array( 'thumbnail', 'comments' ) );

This function is very useful if you need to work with a custom post type that is defi ned in a separate plugin or theme. Rather than hacking the registration code in that plugin or theme, you can use the add_post_type_support() function to enable any feature needed for your code to work. WordPress also features a function to change the post type of a post entry. You can do so by using the set_post_type() function.

The function accepts two parameters: 1. $post_id — The ID of the post you want to update. This fi eld is required. 2. $post_type — The post type name to change the post to. This is an optional fi eld and defaults to post.

c07.indd 125 12/6/12 1:31 AM 126 ❘ CHAPTER 7 CUSTOM POST TYPES, CUSTOM TAXONOMIES, AND METADATA

WORDPRESS TAXONOMY

Taxonomy is defi ned as a way to group similar items together. This basically adds a relational dimension to your website’s content. In the case of WordPress, you use categories and tags to group your posts. By grouping these posts, you are defi ning the taxonomy of those posts. Taxonomy can be hierarchical (that is, categories and subcategories), but it is not required as with the case of tags.

Default Taxonomies By default, WordPress comes loaded with three taxonomies: 1. Category — A bucket for grouping similar posts together 2. Tag — A label attached to a post 3. Link category — A bucket for grouping similar links together Categories are hierarchical and defi ned when creating a post. Tags do not use hierarchy and are also defi ned when creating a post. Link categories are used when grouping similar links together using the WordPress link manager. All three out-of-the-box taxonomies are available for use in a default installation of WordPress. Each category or tag you create is a term of that taxonomy. For example, a category named Music is a term of the category taxonomy. A tag named Ketchup is a term of the tag taxonomy. Understanding taxonomy and terms will help you when defi ning your own custom taxonomies in WordPress. Understanding how you can classify your content using a solid taxonomy structure will make structuring website content in WordPress much easier from the start. Developing a solid taxonomy framework enables easy and accurate information access throughout your website.

Taxonomy Table Structure WordPress features three database tables that store all taxonomy information: wp_terms, wp_term_ relationships, and wp_term_taxonomy. This taxonomy schema, which was added in WordPress 2.3, makes the taxonomy functionality extremely fl exible in WordPress. This means you can create and defi ne any type of custom taxonomy to use on your website.

The wp_terms table stores all of your taxonomy terms. This can be categories, tags, link categories, and any custom taxonomy terms you have defi ned. The wp_term_taxonomy table defi nes what taxonomy each term belongs to. For example, all of your tag IDs will be listed in this table with a taxonomy value of post_tag. If you created a custom taxonomy, the taxonomy value would be the name of your custom taxonomy. The wp_term_relationships table is the cross-reference table that joins taxonomy terms with your content. For example, when you assign a tag to your post, a new record is created here joining your post ID and the term ID together.

c07.indd 126 12/6/12 1:31 AM WordPress Taxonomy ❘ 127

Understanding Taxonomy Relationships To really understand the relationship between the taxonomy tables, it’s helpful to look at a database diagram of the taxonomy table structure, as shown in Figure 7-2.

wp_term_relationships object_id BIGINT(20) term_taxonomy_id BIGINT(20) term_order INT(11) Indexes PRIMARY term_taxonomy_id

wp_term_taxonomy term_taxonomy_id BIGINT(20) term_id BIGINT(20) taxonomy VARCHAR(32) description LONGTEXT wp_term parent BIGINT(20) count BIGINT(20) term_id BIGINT(20) Indexes name VARCHAR(200) slug VARCHAR(200) PRIMARY term_group BIGINT(10) term_id_taxonomy Indexes taxonomy PRIMARY slug name

FIGURE 7-2: WordPress taxonomy table structure

As you can see, the three taxonomy tables are joined together by unique IDs. The following is a query to display all posts along with all taxonomy terms assigned to those posts:

SELECT wt.name, wp.post_title, wp.post_date FROM wp_terms wt INNER JOIN wp_term_taxonomy wtt ON wt.term_id = wtt.term_id INNER JOIN wp_term_relationships wtr ON wtt. term_taxonomy_id = wtr.term_taxonomy_id INNER JOIN wp_posts wp ON wtr.object_id = wp.ID WHERE wp.post_type = 'post'

Notice how you are joining on the table fi elds, as depicted in Figure 7-2. The preceding example returns only three fi elds: the taxonomy term, post title, and post date. This query example returns all posts in your WordPress database along with all taxonomy terms attached to those posts.

NOTE To learn more about taxonomy table relationships and why WordPress needs to decompose these multi-valued relationships into multiple tables, see the WordPress Taxonomy Tables section of Chapter 6: Data Management.

c07.indd 127 12/6/12 1:31 AM 128 ❘ CHAPTER 7 CUSTOM POST TYPES, CUSTOM TAXONOMIES, AND METADATA

BUILDING YOUR OWN TAXONOMIES

Creating your own custom taxonomies has many benefi ts. Imagine running a food blogging website. When creating new posts, you’ll want to label a certain recipe as Asian, but you also may want to label the individual ingredients, heat factor, prep time, and so on. Building custom taxonomies allows you the freedom to defi ne these different methods of categorizing your content and really expands WordPress from blogging software into a full-fl edged content management system (CMS).

Custom Taxonomy Overview With the revamp of the taxonomy schema in WordPress 2.3, you now have the capability to defi ne custom taxonomies for your content. WordPress makes it easier than ever to create custom taxonomies, as well as integrate your new taxonomies into WordPress. WordPress 2.8 added the feature to automatically display a meta box to the post type edit screen for adding taxonomy terms directly to your posts. WordPress will also create a menu item to access the new taxonomy admin panel for administering your taxonomy terms.

Creating Custom Taxonomies Now it’s time to build your fi rst custom taxonomy! You are going to create a simple taxonomy for defi ning Types for your product custom post type registered earlier in this chapter. If you are selling Products online, you’ll need a way to group specifi c Product types together. You are going to set up a custom taxonomy to defi ne each type of Product in WordPress.

First, you are going to defi ne your new taxonomy using the register_taxonomy() WordPress function. This function allows you to customize how your new taxonomy will work and look. The following code would work in a custom plugin, but for this example, you’ll use the functions.php fi le in your theme folder. Open up functions.php in your theme and add the following code:

function prowp_define_product_type_taxonomy() {

register_taxonomy( 'type', 'products', array( 'hierarchical' => true, 'label' => 'Type', 'query_var' => true, 'rewrite' => true ) );

} ?>

The taxonomy defi nition starts by calling the init hook, which tells WordPress to execute your prowp_define_product_type_taxonomy() function during initialization. Your function then calls the WordPress function register_taxonomy(). This function is used to create your custom taxonomy based on what values you send.

c07.indd 128 12/6/12 1:31 AM Building Your Own Taxonomies ❘ 129

You can now break down the parameters you are sending to the register_taxonomy() function. The fi rst parameter is the taxonomy name, in this case type. This is the name that will defi ne this taxonomy in the database. The second parameter is the object type. For this example, you will use products, which is the name of your custom post type. The third and fi nal parameter is for arguments, meaning you actually send multiple values to this parameter.

In this example, you’ll pass four arguments. The fi rst is hierarchical, which defi nes whether or not your custom taxonomy can support nested taxonomies, forming a hierarchy. In the preceding example, you set this to true, so your taxonomy will function just like WordPress’ built-in categories that may contain sub-categories. The next argument, label, is used to set the name of your taxonomy for use in admin pages within WordPress. If the query_var argument is set to false, then no queries can be made against the taxonomy; if true then the taxonomy name (with dashes replacing spaces) is used as a query variable in URL strings. Specifying a string value for the query_var overrides the default. For example, query_var => 'strength' would permit URL strings of the form example.com/?strength=weapons to be used to select content from the custom taxonomy.

The fi nal argument is for rewrite, which you set to true. This tells WordPress whether or not you want a pretty permalink when viewing your custom taxonomy. By setting this to true you can access your custom taxonomy posts such as example.com/type/weapons rather than the ugly method of example.com/?type=weapons.

Now that you have created your custom taxonomy for type, take a look at FIGURE 7-3: Custom what WordPress has done with your new taxonomy. The fi rst thing you will taxonomy menu notice on your admin dashboard is a new link under the Products menu for option your taxonomy labeled Type, as shown in Figure 7-3. Clicking this new menu item brings you to the custom taxonomy admin panel for types, shown in Figure 7-4. This admin panel works exactly as the post categories admin panel does. Here you can create new taxonomy terms, edit and delete existing terms, fi nd how many products are assigned to each, and also search taxonomy terms.

FIGURE 7-4: Custom taxonomy admin panel

c07.indd 129 12/6/12 1:31 AM 130 ❘ CHAPTER 7 CUSTOM POST TYPES, CUSTOM TAXONOMIES, AND METADATA

The fi nal new item added for your custom taxonomy is a meta box on the product edit screen, shown in Figure 7-5. To view this, click Add New Product. The meta box appears on the right side of your screen and looks very similar to the Category meta box. Here you can easily add and delete new types on your products. As with custom post types, you can set a variety of different arguments when registering a custom taxonomy:

➤ public — Sets whether a custom taxonomy is publicly available on the admin dashboard or front-end of your website. By default, this is set to true. The default settings for show_ui and show_in_nav_menus are inherited from this setting. ➤ show_ui — Sets whether to create a default UI in the WordPress admin dashboard for managing this taxonomy. Defaults to the value defi ned by the public argument. ➤ show_in_nav_menus — Sets whether the post type is FIGURE 7-5: Custom taxonomy available for selection in the menu management feature of meta box WordPress. Defaults to the value defi ned by the public argument. ➤ show_tagcloud — Sets whether to allow the built-in Tag Cloud widget to use this taxonomy. Defaults to the value defi ned by the show_ui argument. ➤ hierarchical — Sets whether this custom taxonomy is hierarchical (like categories) or not hierarchical (like tags). By default, this argument is set to false. ➤ update_count_callback — Function name that will be called when a term in your taxonomy gets a count update. The default value is none. ➤ query_var — Enables the public query var for the taxonomy. Acceptable values are true, false, or a string to set a custom query var value. ➤ rewrite — The rewrite argument sets the URL parsing rules for permalinks referring to this taxonomy. This allows you to customize the taxonomy slug in your URL. This argument can be set to true, false, or an array of values. If passing an array, it accepts the following values. By default this argument is set to true and the $taxonomy name is used as the slug. ➤ slug — Set a custom permalink slug. Defaults to the taxonomy name value. ➤ with_front — Sets whether your taxonomy should use the front base from your permalink settings. For example, if you prefi xed your permalinks with /blog, and with_front is set to true, your taxonomy permalinks would include /blog at the beginning. ➤ hierarchical — Allow hierarchical URLs. Defaults to false. To learn more about the register_taxonomy() function, visit the offi cial Codex page at http:// codex.wordpress.org/Function_Reference/register_taxonomy.

c07.indd 130 12/6/12 1:31 AM Building Your Own Taxonomies ❘ 131

Setting Custom Taxonomy Labels Similar to creating a custom post type in WordPress, custom taxonomies feature several text strings that are shown throughout the WordPress admin dashboard for your taxonomy. These text strings are typically a link, button, or extra information about the custom taxonomy. By default, the term “Tag” is used for non-hierarchical taxonomies and “Category” for hierarchical taxonomies. The available labels for your custom taxonomy include:

➤ name — General name for the taxonomy, which is usually plural. ➤ singular_name — The singular version of the name for the taxonomy. ➤ search_items — Text for the search items button. ➤ popular_items — Label for popular items text. ➤ all_items — Label for all items text. ➤ parent_item — The parent item text. Not used on non-hierarchical taxonomies. ➤ parent_item_colon — Same as parent_item, but with a colon at the end. ➤ edit_item — Used as the text for editing an individual taxonomy term. ➤ update_item — Used as the text for updating an individual taxonomy term. ➤ add_new_item — Text for creating a new taxonomy term. ➤ new_item_name — The new item text name text. ➤ separate_items_with_commas — The separate items with commas text used in the taxonomy meta box. Not used on hierarchical taxonomies. ➤ add_or_remove_items — Text displayed in the taxonomy meta box when JavaScript is disabled. Not used on hierarchical taxonomies. ➤ choose_from_most_used — The choose from most used text used in the taxonomy meta box. Not used on hierarchical taxonomies. ➤ menu_name — The menu name text. Defaults to the value of name. Setting these labels makes it much easier on users when administering custom taxonomy terms. Now modify the custom taxonomy registration code from earlier with custom labels:

function prowp_define_product_type_taxonomy() {

$labels = array( 'name' => 'Type', 'singular_name' => 'Types', 'search_items' => 'Search Types', 'all_items' => 'All Types', 'parent_item' => 'Parent Type', 'parent_item_colon' => 'Parent Type:',

c07.indd 131 12/6/12 1:31 AM 132 ❘ CHAPTER 7 CUSTOM POST TYPES, CUSTOM TAXONOMIES, AND METADATA

'edit_item' => 'Edit Type', 'update_item' => 'Update Type', 'add_new_item' => 'Add New Type', 'new_item_name' => 'New Type Name', 'menu_name' => 'Type' );

$args = array( 'labels' => $labels, 'hierarchical' => true, 'query_var' => true, 'rewrite' => true );

register_taxonomy( 'type', 'products', $args );

} ?>

Using Your Custom Taxonomy Now that you’ve created your custom taxonomy, you need to know how to use it on your website. As always, WordPress features some very easy-to-use functions for working with your custom taxonomy. The following shows how you can display a tag cloud showing your custom taxonomy terms:

'type', 'number' => 5 ) ); ?>

The wp_tag_cloud() function can accept many different arguments, but in this example, you’re using only two: taxonomy and number. First, you set your taxonomy to type; this tells WordPress to return only taxonomy terms defi ned under the custom taxonomy you created for types. Next, you defi ne the number of terms you want to display, which in this example is 5. Calling this function in your theme sidebar displays a nice tag cloud that shows the fi ve taxonomy terms with the most products assigned to them.

You can also create a custom Loop using WP_Query to display products for a specifi c taxonomy term. Say you want to create a custom Loop to display only products that are in the weapon type:

'products', 'tax_query' => array( array( 'taxonomy' => 'type', 'field' => 'slug', 'terms' => 'weapon' ) ) );

$products = new WP_Query( $args );

while ( $products->have_posts() ) : $products->the_post();

c07.indd 132 12/6/12 1:31 AM Metadata ❘ 133

echo '

' .get_the_title(). '

'; endwhile;

wp_reset_postdata(); ?>

That’s it! The two WP_Query arguments you send are the post_type, products in this case, and the tax_query, which specifi es which taxonomy term to use. You can also easily display custom taxonomy terms assigned to each post. To do this, you’ll be using the get_the_term_list() WordPress function. This function works very similarly to get_the_ tag_list() but is for building a custom taxonomy term list instead.

ID, 'type', 'Product Type: ', ', ', '' ); ?>

The preceding code displays all custom taxonomy terms assigned to the post you are viewing. This code does need to be in the Loop in your theme template fi le to work correctly. To execute the function, you send in the post ID, custom taxonomy name, and the title you want displayed next to the terms. Remember that you can always visit the function reference to learn more about this function and what parameters are allowed: http://codex.wordpress.org/Function_Reference/ get_the_term_list.

The get_terms() function can also be used to retrieve an array of your custom taxonomy values. In the following example, you retrieve all of the terms for your type taxonomy and loop through the values displaying the term name:

' .$term->name. '

'; } ?>

Keep in mind that you need to make sure the taxonomy is defi ned before you start working with custom taxonomy values. If any of the preceding examples return blank, that means they were executed before your register_taxonomy() function was called to defi ne your custom taxonomy. Defi ning custom taxonomies in WordPress is a very powerful way to organize your website content. Using the preceding methods can help transform your website into a content management system using the power of WordPress.

METADATA

In this chapter, you’ve learned how to create custom post types to add to the basic content types managed by WordPress, and custom taxonomies to organize and collect those content types. This chapter wraps up with a look at extending the content management descriptors of a post with custom metadata.

c07.indd 133 12/6/12 1:31 AM 134 ❘ CHAPTER 7 CUSTOM POST TYPES, CUSTOM TAXONOMIES, AND METADATA

What Is Metadata? Metadata in WordPress refers to additional pieces of data attached to a post. For example, your products custom post type might need a price stored with each Product entered. The price could be stored as metadata and easily displayed on the Product detail page. Post metadata is often referred to as Custom Fields in WordPress terminology. This is a more user-friendly term in the admin dashboard of WordPress. WordPress adds a Custom Fields meta box on the post-editing screen by default, as shown in Figure 7-6. If a custom post type has the custom-fields value defi ned for the supports argument, this meta box will also appear.

FIGURE 7-6: Custom Field meta box

All post metadata is stored in the wp_postmeta table in your WordPress database.

Adding Metadata WordPress features a simple function to add new post metadata called add_post_meta(). This function will attach a piece of metadata to the post specifi ed as follows:

This function accepts the following four parameters: 1. $post_id — The ID of the post to add metadata. 2. $meta_key — The name of the metadata fi eld. 3. $meta_value — The value of the metadata fi eld. 4. $unique — A value identifying whether or not the key should be unique. The default value is false. Now that you understand the parameters for the add_post_meta() function, you can use it to add some metadata to your products.

add_post_meta( 420, 'prowp_price', '34.99', true );

This code example adds a metadata entry called prowp_price with a value of 34.99 to product ID 420. You also set the $unique value to true, which means there cannot be multiple entries for the

c07.indd 134 12/6/12 1:31 AM Metadata ❘ 135

prowp_price fi eld on this product. Now if you edit the product in WordPress, you will see a prowp_ price fi eld and value in the custom fi elds meta box.

NOTE To prevent metadata keys from appearing in the Custom Fields meta box on the Post Edit screen, prefi x the meta key with an underscore like _prowp_ price. This will hide the data from the user and is common practice when creating custom meta boxes.

Updating Metadata As easy as it is to add new metadata to a post, you can also update metadata using the update_ post_meta() function. This function will update a piece of metadata attached to a post specifi ed, as shown here. If the meta key does not already exist, the function will create it.

This function accepts the following parameters:

➤ $post_id — The ID of the post to update metadata. ➤ $meta_key — The name of the metadata fi eld. ➤ $meta_value — The value of the metadata fi eld. ➤ $prev_value — The old value of the metadata fi eld to update. This is to differentiate between several fi elds with the same key and is an optional fi eld. For an example, you can update the price on your product from earlier as follows:

update_post_meta( 420, 'prowp_price', '6.99' );

The preceding code example updates the previously added metadata fi eld prowp_price to 6.99 for product ID 420.

Deleting Metadata Now that you understand how to add and update post metadata, you can learn how to delete that data. To delete post metadata, you’ll use the delete_post_meta() function.

This function accepts the following parameters:

➤ $post_id — The ID of the post to delete metadata from. ➤ $meta_key — The name of the metadata fi eld. ➤ $meta_value — The value of the metadata fi eld. This is to differentiate between several fi elds with the same key and is an optional fi eld.

c07.indd 135 12/6/12 1:31 AM 136 ❘ CHAPTER 7 CUSTOM POST TYPES, CUSTOM TAXONOMIES, AND METADATA

Let’s delete the post metadata you created earlier:

delete_post_meta( 420, 'prowp_price' );

The preceding code example will delete the prowp_price metadata from product ID 420. You did not defi ne the $meta_value parameter, so all prowp_price entries will be deleted from product ID 420.

Retrieving Metadata You’ve covered how to add, update, and delete metadata, so now you will review how to retrieve and display metadata. WordPress makes it easy to retrieve post metadata for display or use in other code. A good place to use this code is within a Loop to display custom metadata for a particular piece of content.

To retrieve metadata, you’ll use the get_post_meta() function:

The function accepts these parameters:

➤ $post_id — The ID of the post to retrieve metadata for. ➤ $meta_key — The name of the metadata fi eld. ➤ $single — A value identifying whether to return a single meta value fi eld (true) or return an array of values (false). By default, this parameter is set to false. Let’s retrieve and display the price for your product created earlier:

$product_price = get_post_meta( 420, 'prowp_price', true ); echo 'Price $' .$product_price;

The product price is retrieved and displayed for product ID 420. Now assume you want to store various colors for the product. Instead of creating a separate metadata entry for each color, you’ll create an array of color entries in a single metadata fi eld:

$product_colors = get_post_meta( 420, 'prowp_colors', false );

echo '

foreach ( $product_colors as $color ) { echo '

' .$color .'

echo '

'; ?>

c07.indd 136 12/6/12 1:31 AM Summary ❘ 137

First you have to create the metadata entries for the product colors. This is done using the add_post_meta() function. Next, set the meta key name to the same and the $unique parameter to false, which will allow multiple entries under the same meta key.

Next, you’ll use the get_post_meta() function to retrieve the product colors you just set. Notice the $single parameter is set to false, which allows you to return all entries for prowp_colors for product ID 420 as an array. Finally, you’ll loop through the colors array and display each product color.

Another powerful function for retrieving post metadata is the get_post_custom() function. This function returns a multidimensional array of all metadata for a particular post.

This function accepts a single required parameter — $post_id — the ID of the post whose custom fi elds will be retrieved. Let’s retrieve and display all metadata entries for your product:

foreach( $product_metadata as $name => $value ) {

echo '' .$name .' => ';

foreach( $value as $nameAr => $valueAr ) { echo '
' .$nameAr." => "; echo var_dump( $valueAr ); }

echo '
';

} ?>

The preceding code example will retrieve all metadata for product ID 420. Because the value returned is a multidimensional array, you have to do multiple loops to display all of the data. If you are retrieving multiple pieces of metadata for a post, this is the optimized method because it retrieves all metadata in a single database query instead of running separate queries for each piece of data requested. As you can tell, this is a more advanced method for retrieving post metadata.

SUMMARY

It’s very easy to see how using a combination of custom post types, custom taxonomies, and metadata in WordPress opens the doors to endless possibilities. These features have morphed WordPress from a simple blogging platform into a full-fl edged content management system capable of handling any type of data you can conceive. In the next chapter you’ll dive into creating custom plugins for WordPress. You’ll learn the proper ways to integrate into various areas of WordPress, understanding data validation to develop secure code, and even how to publish your plugins to the WordPress.org Plugin Directory.

c07.indd 137 12/6/12 1:31 AM c07.indd 138 12/6/12 1:31 AM 8 Plugin Development

WHAT’S IN THIS CHAPTER?

➤ Creating plugin ﬁ les ➤ Data validation and plugin security ➤ Using WordPress ﬁ lter and action hooks ➤ How to properly use the Settings API ➤ Creating a widget and dashboard widget ➤ Creating custom shortcodes ➤ Supporting language translation ➤ Publishing a plugin to the offi cial Plugin Directory

WROX.COM CODE DOWNLOADS FOR THIS CHAPTER The wrox.com code downloads for this chapter are found at www.wrox.com/remtitle .cgi?isbn=9781118442272 on the Download Code tab. The code is in the Chapter 8 download fi le and individually named according to the code fi le names throughout the chapter. One of the main reasons WordPress is such a popular software platform is the ease with which it can be extended. Plugins are the primary reason for this and allow endless possibilities in extending WordPress. This chapter discusses everything you need to know to create amazing plugins in WordPress. You are going to look at plugins from both a functional and structural perspective. Starting with the packaging of plugin fi les, you’ll dig into the API hooks that connect your custom plugin code to the WordPress core and show how to integrate a plugin into various parts of the WordPress editing, management, and display processes. Finally, you will see how to publish a plugin for others to use. At the end of this chapter, you build a WordPress plugin from the

c08.indd 139 12/6/12 1:19 AM 140 ❘ CHAPTER 8 PLUGIN DEVELOPMENT

ground up. You’ll utilize many of the features discussed in this chapter and learn the proper way to extend WordPress through a custom plugin.

PLUGIN PACKAGING

When developing plugins in WordPress, it’s best to follow a standard plugin packaging template — that is, certain functional and descriptive components that will exist in all plugins you create for WordPress. This chapter discusses the requirements for a plugin, as well as recommended additions such as software license and internationalization. While the actual code implementation of the plugin is the exciting part of the process, consider the plugin packaging similar to elementary grammar rules for a new language: necessary for making yourself understood.

Creating a Plugin File The fi rst step in creating a WordPress plugin is to create a new PHP fi le for your plugin code. The plugin fi le name should be descriptive of your plugin so it’s easy to identify your plugin in the plugins directory. It should also be unique because all WordPress plugins exist in the same folder. If your plugin fi le name is too generic, you run the risk of another plugin having the same fi le name, which would be an obvious problem. A plugin can also exist in a folder containing all of the necessary fi les the plugin needs to run. A folder should always be used because it helps keep the user’s plugin folder organized. It’s also a good idea to maintain a clean folder structure, which refers to keeping all similar fi les together. For example, if your plugin includes images, you should create an /images folder inside your plugin folder to store any custom images your plugin might use. Let’s look at a standard folder structure for a plugin:

➤ /unique-plugin-name (no spaces or special characters) ➤ unique-plugin-name.php — Primary plugin PHP fi le ➤ uninstall.php — The uninstall fi le for your plugin ➤ /js — Folder for JavaScript fi les ➤ /css — Folder for style sheet fi les ➤ /includes — Folder for additional PHP includes ➤ /images — Folder for plugin images Keeping your fi les organized using a clean folder structure can make it much easier to track the fl ow of your plugin over time.

Creating the Plugin Header A requirement for all WordPress plugins is a valid plugin header. The plugin header must be defi ned at the very top of your main PHP fi le as a PHP comment. It does not need to exist in every fi le for your plugin, only the main PHP fi le. This header tells WordPress that your PHP fi le is in fact a

c08.indd 140 12/6/12 1:19 AM Plugin Packaging ❘ 141

legitimate WordPress plugin and should be processed as such. Following is an example of a standard plugin header: The only required line in the plugin header is the Plugin Name. The rest of the information is optional but highly recommended. The information FIGURE 8-1: Example plugin listing listed in your plugin header is used on the Manage Plugins section of WordPress. You can see what the header looks like in WordPress in Figure 8-1. You can see how important the plugin header information is, including all optional data. The information should be accurate and provide good links to your website and the plugin URI for additional information and support regarding your plugin.

Plugin License When developing a plugin you plan on releasing to the public, it’s customary to include the software license that the plugin is released under just below your plugin header. This is not a requirement for the plugin to function, but is a good idea to clearly state what software license your plugin uses. A license comment block will also state that there is no warranty, which protects you from liability should someone decide your plugin destroyed his or her site. Following is a standard GPL license, under which most WordPress plugins are released:

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ ?>

c08.indd 141 12/6/12 1:19 AM 142 ❘ CHAPTER 8 PLUGIN DEVELOPMENT

To use this license in your plugin fi ll in the year, plugin author name, and plugin author e-mail in the preceding comment. By doing so your plugin will be licensed under the GPL. WordPress is licensed under the GPLv2 software license. This is a very common software license for open source projects. Since plugins are dependent on WordPress to function, they should also be released under a GPL, or compatible, software license. For more information on GPL licensing visit http://www.gnu.org/licenses/licenses.html.

Activating and Deactivating Functions You’ll want to utilize some important functions when creating plugins. The fi rst of these is called the register_activation_hook() function. This function is executed when your plugin is activated in the WordPress Plugins SubPanel. The function accepts two parameters: the path to the main plugin fi le and the function to execute when the plugin is activated.

In most of the code examples in this chapter, you’re going to use prowp as a function and variable prefi x, as well as a descriptive name for your plugin. It’s just an example short name, but one that you’re going to see in a lot of code. The following example executes the function prowp_install() when the plugin is activated:

function prowp_install() { //do something } ?> This is an extremely useful function if you need to execute any actions when your plugin is activated. For example, you may want to check the current WordPress version to verify that your plugin is compatible. You may also want to create some default option settings. One important check you should always do when your plugin is activated is to verify that the version of WordPress the user is running is compatible with your plugin. This ensures any functions, hooks, and so on that your plugin uses are available in WordPress.

function prowp_install() { global $wp_version;

if ( version_compare( $wp_version, '3.5', '<' ) ) {

wp_die( 'This plugin requires WordPress version 3.5 or higher.' );

} } ?>

The preceding function uses the global variable $wp_version, which stores the currently running version of WordPress, and verifi es that it is not running a version lower than 3.5. You do the version comparison using the version_compare() PHP function. If the WordPress version is lower than 3.5, you display an error message to the users that they need to update.

c08.indd 142 12/6/12 1:19 AM Plugin Packaging ❘ 143

There is also a function that executes when a plugin is deactivated called register_deactiva- tion_hook(). This function is executed when your plugin is deactivated in the WordPress Plugins SubPanel. This function accepts the same two arguments as the register_activation_hook function. Following is an example using the deactivation function:

function prowp_deactivate() { //do something } ?>

NOTE It’s important to remember that deactivating is not uninstalling. You should never include uninstall functionality in your deactivation function. Imagine that a user accidentally deactivates your plugin and all of their settings are deleted. That would not be a good user experience and should be avoided.

Internationalization Internationalization, sometimes shortened to “i18n” in the WordPress Codex, is the process of making your plugin or theme ready for translation, or localized. In WordPress, this means marking strings that should be translated. Localization is the process of translating the text displayed by the theme or plugin into different languages. This isn’t a requirement, but internationalization should be used on any plugin you plan on distributing. This opens up your plugin to the widest possible audience.

WordPress features many different functions to make a string translatable. The fi rst function is __ (). That isn’t a typo; the function is two underscores, as shown here: The fi rst parameter you pass is the string that you want to be translated. This string is what will be displayed to the browser if the text is not translated into a different language. The second parameter is the text domain. In the case of themes and plugins, the domain should be a unique identifi er, which is used to distinguish between all loaded translations.

If your code should echo the translatable string to the browser, you’ll want to use the _e() function, as shown here:

This function works exactly the same as __(); the only difference is that the value is echoed to the browser. Placeholders need special consideration when internationalizing your plugins and themes. As an example, look at an error message you want to make translatable: Error Code 6980: Email is a required field

c08.indd 143 12/6/12 1:19 AM 144 ❘ CHAPTER 8 PLUGIN DEVELOPMENT

The obvious, but incorrect, way to attempt to split a string into translatable parts is to separate the fi eld name, error number, and descriptive string:

echo $error; ?> This is actually the wrong way to include dynamic values in your translatable string because your translatable string is cut into two parts. These two parts may not work independently in another language. This could also seriously confuse the translator viewing a bunch of cryptic phrases that mean nothing when separated. The proper way is shown here:

As you can see, this uses the PHP printf() function, which outputs the formatted string. Your two variables are passed to printf() and inserted into the string in the designated spots. In this example, a developer translating your plugin messages into another language would see the line as Error Code %1$d: %2$s is a required field and know it’s possible to move around the error number and fi eld values to make sense in the target language. Splitting the strings leads to split translations and possibly unintentionally funny translated grammar. Alternatively, you could use the PHP sprintf() function if you want to store the error message value in a variable prior to displaying it. Plurals also need special consideration when defi ning your translatable strings. Say you need to translate a string like this: This works great if you have one new message, but what if you have more than one new message? Fortunately, WordPress contains a function you can use to handle this problem called _n(). The following code shows it in action: This function accepts four parameters: the singular version, the plural version, the actual number, and the domain text for your plugin. The _n() function uses the number parameter ( $count in the example) to determine whether the singular or plural string should be returned.

c08.indd 144 12/6/12 1:19 AM Plugin Packaging ❘ 145

WordPress also features a translation function you can use to add comments to your translatable strings. This is helpful if you have a string set up for translation that might have multiple meanings. To do this, you use the _x() function, as shown in the following code: As you can see, there are three parameters for this function. The fi rst is the text string to translate. The second, and most important, is the context information for the translators. This allows you to add custom comment messages that the translator can read to explain the context of your text to be translated. The fi nal parameter is the text domain. Now that you’ve prepared your plugin for translation, you must load the localization fi le to do the translation. To do so, you execute the load_plugin_textdomain() function as shown here:

function prowp_init() { load_plugin_textdomain( 'prowp-plugin', false, plugin_basename( dirname( __FILE__ ) .'/localization' ) ); } ?> The fi rst parameter you pass is the domain text name that you’ve used to identify all of your translatable strings. The second parameter is the path relative to the ABSPATH variable; however, this parameter is now deprecated in favor of the third parameter. The fi nal parameter is the path to your translation fi les from the /plugins directory. To store these fi les, you should create a folder inside your plugin directory called /localization . You use the plugin_basename() and dirname() functions to retrieve the path to your localization folder. You can learn more about the process of creating translation fi les in the WordPress Codex at http://codex.wordpress.org/I18n_for_WordPress_Developers.

Determining Paths When creating WordPress plugins, you will often need to reference fi les and folders throughout the WordPress installation. Since WordPress 2.6, users have had the ability to move this directory anywhere they want. Because of this, you should never use hard-coded paths in a plugin. WordPress has a set of functions to determine the path to the wp-content and plugins directories, as well as directories within your plugins. You can use these functions in your plugins to verify that any paths you are referencing are correct regardless of where the actual directory might exist on the server.

Local Paths To determine the local server path to your plugin, you’ll use the plugin_dir_path() function. This function extracts the physical location relative to the plugins directory from its fi le name.

c08.indd 145 12/6/12 1:19 AM 146 ❘ CHAPTER 8 PLUGIN DEVELOPMENT

You can see that you pass the __FILE__ PHP constant to the plugin_dir_path() function. This returns the full local server path to your plugin directory: /public_html/wp-content/plugins/halloween-plugin/ Now let’s assume you need to reference the local path to a fi le in a subdirectory in your plugin. You can use the plugin_dir_path() function along with the subdirectory and fi les you want to reference, as shown here: The preceding example would produce the following result: /public_html/wp-content/plugins/halloween-plugin/js/script.js URL Paths To determine the full URL to any fi le in your plugin directory, you’ll use the plugins_url() function as shown here:

You can see the plugins_url() function accepts two parameters. The fi rst parameter is the path relative to the plugins URL. The second parameter is the plugin fi le that you want to be relative to. In this case, you’ll use the __FILE__ PHP constant. The preceding example will return a full URL to your plugin’s icon.png fi le located in the images directory, as shown here:

The following is a list of the many advantages of using the plugins_url() function to determine plugin fi le URLs:

➤ Supports the /mu-plugins plugin directory ➤ Auto detects SSL. If SSL is enabled, the returned URL would contain https:// ➤ Can detect the location of the plugin even if the user has moved his /wp-content directory to a custom location ➤ Supports Multisite WordPress also features various functions to determine URLs in WordPress. The following is a list of the functions available:

➤ admin_url() — Admin URL (http://example.com/wp-admin/) ➤ site_url() — Site URL for the current site (http://example.com) ➤ home_url() — Home URL for the current site (http://example.com) ➤ includes_url() — Includes directory URL (http://example.com/wp-includes/) ➤ content_url() — Content directory URL (http://example.com/wp-content/) ➤ wp_upload_dir() — Returns an array with location information on the confi gured uploads directory Understanding the proper way to access fi les in your plugins is essential to ensure maximum compatibility with all WordPress installations, regardless of how customized they are.

c08.indd 146 12/6/12 1:19 AM Plugin Security ❘ 147

PLUGIN SECURITY

One of the most important steps in creating a plugin is making sure it is secure from hacks and exploits. If a plugin contains security holes, it opens up the entire WordPress website for malicious hackers to wreak havoc. WordPress features some built-in security tools that you should always utilize to make sure your plugins are as secure as can be. Remember that all data external to your plugin code is suspect until proven valid. Always validate your data before displaying to the browser or inserting into the database to help keep your plugins secure from hacks and exploits. You’ll be using the mentioned escaping and sanitizing functions discussed in this section throughout the chapter.

Nonces Nonces, which stands for “number used once,” are used in requests (saving options, form posts, Ajax requests, actions) to stop unauthorized access by generating a secret key. This secret key is generated prior to generating a request (that is, form post). The key is then passed in the request to your script and verifi ed to be the same key before anything else is processed. Now let’s look at how you can manually create and check nonces. The following example uses a nonce in a form:

When creating a form nonce, the function wp_nonce_field() must be called inside of your

tags. There are actually no required parameters for this function to work, but for increased security there are two parameters you should set. The fi rst parameter is $action, which should be a unique string that is descriptive of the action being performed. The second parameter is a unique name for the fi eld, $name. By default, the fi eld name will be _wpnonce, but you can defi ne a custom unique name in this parameter.

When the wp_nonce_field() function is called, it will generate a unique secret key that will be added as a hidden form fi eld and passed with your form data. After your form is posted, the fi rst thing you need to do is check your nonce secret key using the check_admin_referer() function like so: function prowp_update_options() {

if ( isset( $_POST['submit'] ) ) {

//check nonce for security check_admin_referer( 'prowp_settings_form_save', 'prowp_nonce_field' );

//nonce passed, now do stuff

} }

c08.indd 147 12/6/12 1:19 AM 148 ❘ CHAPTER 8 PLUGIN DEVELOPMENT

Verifying that the nonce is valid is as simple as calling the check_admin_referer() function and passing it your unique nonce action and name that you defi ned earlier. If the nonce secret key does not match the secret key created on your form, WordPress will stop processing the page and issue an error message. This primarily protects it from cross-site request forgery, or CSRF. Nonces can also be used on links that perform actions. To create a URL nonce, you use the wp_nonce_url() function. This can be used in conjunction with multiple query strings in your URL like so: Delete

The wp_nonce_url() function accepts two parameters: the URL to add the nonce to and the unique nonce name you are creating. The preceding code would generate a link that looks like this: http://example.com/wp-admin/my-url.php?action=delete&ID=15&_wpnonce=e9d6673015

Notice how the _wpnonce query string is appended to the link. This is the secret key value that was generated for your URL nonce. If your URL has no query strings, the wp_nonce_url() function will add the nonce value as the only query string being passed. If your URL contains query strings, that nonce value will be added to the end of the URL. You can verify that the nonce is correct just as you did with your form — by using the check_admin_referer() function: function prowp_update_options() {

if ( isset( $_GET['action'] ) ) {

//check nonce for security check_admin_referer( 'prowp_nonce_url_check' );

//do stuff } } This function verifi es that your action query string is set before checking your nonce value. Once the nonce has been validated, the script will continue. Remember that if the nonce is not validated, the page execution will stop, preventing any type of hack attempt.

Data Validation and Sanitization Any data that comes from somewhere external to your code (such as user input) needs to be scrubbed to verify that it’s free from illegal characters and potentially unsafe data. Data validation is essential to proper plugin security. Improperly validated data can lead to SQL injection hacks, exploits, errors, and much more. WordPress features a set of escaping functions that you can use to verify that your data is escaped properly when being displayed to the screen. These escaping functions follow a set naming standard (see the following list), which makes it easy to identify what they are escaping. Figure 8-2 shows the escaping function naming template.

c08.indd 148 12/6/12 1:19 AM Plugin Security ❘ 149

➤ esc_: The prefi x for the escaping functions. esc_attr_e( ) ➤ attr: The escaping context (attr, html, textarea, js, sql, url, 123 and url_raw). FIGURE 8-2: Escaping API breakdown ➤ _e: The optional translation suffi x. Available suffi xes are __ and _e.

The esc_html() function is used for escaping data that contains HTML. This function encodes special characters into the equivalent HTML entities. These characters include &, <, >, ", and ' as follows:

The esc_attr() function is used for escaping HTML attributes. This function should be used whenever you need to display data inside an HTML element:

The esc_textrea() function is used for escaping HTML values. This function should be used to encode text for use in a <textarea> form element as follows: <textarea name="description"><?php echo esc_textarea( $text ); ?>

WordPress also features a function for validating URLs called esc_url(). This function should be used to scrub the URL for illegal characters. Even though the href is technically an HTML attribute, you should use the esc_url() function like so:

The esc_js() function escapes text strings in JavaScript:

The esc_sql() function escapes data for use in a MySQL query. This function is really just a shortcut for $wpdb->escape()as follows:

The optional translation suffi x ( __ or _e) is used for translating the escaped data. The _e suffi x will echo the escaped translated text, whereas __ only returns the escaped translated value.

//escapes, translates, but does NOT display $text = esc_html__( $text, 'prowp-plugin' ); ?>

If the data you are validating is supposed to be an integer, use the intval() PHP function to verify that. The intval() function will return the integer value of a variable. If the variable is a string, and therefore not an integer, it will return 0. $variable = 12345; $variable = intval( $variable );

c08.indd 149 12/6/12 1:19 AM 150 ❘ CHAPTER 8 PLUGIN DEVELOPMENT

Another useful function for working with integers is the absint() WordPress function. This function ensures that the result is a nonnegative integer: $variable = 12345; $variable = absint( $variable ); WordPress also features some very useful sanitizing functions. These functions should be used to sanitize any data prior to saving it in the database. One of those functions is sanitize_text _field(). This function will remove all invalid UTF-8 characters, convert single < into HTML entities, and remove all HTML tags, line breaks, and extra white space.

You can also sanitize an e-mail address using sanitize_email(). This function will strip out all characters that are not allowable in an e-mail address. Consider the following code:

You can see that the sanitize_email() function removes the extra spaces and illegal characters from the e-mail address submitted.

A very powerful function for processing and sanitizing untrusted HTML is wp_kses(). This function is used in WordPress to verify that only allowed HTML tags and attributes can be submitted by users. By defi ning allowed HTML tags you can avoid cross-site scripting (XSS) attacks through your code. Consider the following example: $allowed_tags = array( 'strong' => array(), 'a' => array( 'href' => array(), 'title' => array() ) );

$html = 'link. This is bold and strong';

echo wp_kses( $html, $allowed_tags ); The fi rst step is to defi ne an array of all HTML tags and attributes. In this example, you are allowing the and tags. The tag is allowed to include the href and title attributes. Next, you build an $html variable to test out the function. The fi nal step is to pass the $html string and $allowed_tags arguments to the wp_kses() function. The preceding example would display the following code: link. This is bold and strong

Notice the tags have been completely removed. The function also removed the class attribute from the tag because you didn’t specify that as an allowed attribute. This basic example really shows the power of this function. Any time you need to allow users to input HTML code, you should always use the wp_kses() function to verify that only acceptable HTML tags and attributes are allowed.

c08.indd 150 12/6/12 1:19 AM Know Your Hooks: Actions and Filters ❘ 151

For more information on data validation in WordPress, check out the following Codex article: http://codex.wordpress.org/Data_Validation.

NOTE Throughout this chapter, you’ll be using various data validation techniques in the code examples. The goal of this is to stress the importance of keeping security in the front of your mind when developing plugins for WordPress.

KNOW YOUR HOOKS: ACTIONS AND FILTERS

One of the most important features for extending WordPress is called a hook. Hooks are simply a standardized way of “hooking” into WordPress. Using hooks, you can execute functions at specifi c times in the WordPress process, allowing you to alter how WordPress functions and the expected output. Hooks are the primary way plugins interact with your content in WordPress. Up to this point, you’ve focused on the structure and format of plugins, but now you’re actually going to make a plugin do something! A hook is simply a PHP function call with various parameters that can be sent. Following is an example showing a properly formatted Action hook call: Actions and Filters Two types of hooks can be used: actions and fi lters. Action hooks are triggered by events in WordPress. For example, an Action hook is triggered when a new post is published. Filter hooks are used to modify WordPress content before saving it to the database or displaying it to the screen. For example, a Filter hook is available for the content of the post or page. This means you can alter that content after it is retrieved from the database but before it is displayed in your browser. Look at an example of a Filter hook in action. Remember that Filter hooks modify content, so this example modifi es the post content:

The add_filter() function is used to execute a Filter action. You are using the fi lter called the_ content, which is the fi lter for your post content. This tells WordPress that every time the content is displayed, it needs to pass through your custom function called prowp_function(). The add_filter() function can accept four parameters: 1. filter_action (string): The fi lter to use 2. custom_filter_function (string): The custom function to pass the fi lter through 3. priority (integer): The priority in which this fi lter should run. When multiple callback functions are attached to the same hook, the priority parameter determines the execution order 4. accepted args (integer): The number of arguments the function accepts

c08.indd 151 12/6/12 1:19 AM 152 ❘ CHAPTER 8 PLUGIN DEVELOPMENT

Here’s an example of the_content fi lter in action:

function prowp_profanity_filter( $content ) {

$profanities = array( 'sissy', 'dummy' ); $content= str_ireplace( $profanities, '[censored]', $content );

return $content;

} ?>

The prowp_profanity_filter() function will replace the words “sissy” and “dummy” with [censored] automatically on all posts and pages on your website. You are using the str_ireplace() PHP function to handle the replacement. This function will replace some characters in a string with other characters in a string. The str_ireplace() function is also case-insensitive. Because you are using a Filter hook, the content isn’t actually modifi ed in the database; instead, it’s modifi ed during processing of the_post(), before being displayed, when this fi lter is invoked. The content in the database is not affected so the words “sissy” and “dummy” will still exist in your content, and if you ever disable or change the plugin, those words will appear in the displayed text. Filter hooks always receive data; in this case, the $content variable is passed to your function and contains your post content. Also notice the last line of your function returns the $content variable. Remember that you must always return the content you are modifying or else it returns empty and therefore displays nothing. Now that you’ve seen the Filter hook in action, take a look at the Action hook and what it can do. The Action hook is triggered by events in WordPress. WordPress doesn’t require any return values from your Action hook function; the WordPress Core just notifi es your code that a specifi c event has taken place. The Action hook is structured exactly like a Filter hook, as you can see in the following code:

The add_action() function accepts four parameters just like the add_filter() function. Here you can set the hook name you want to hook into, the custom function name you are going to execute when the event is triggered, and the priority and the number of accepted args. Here’s a real example using an Action hook:

function prowp_email_new_comment() { wp_mail( '[email protected]', 'New blog comment', 'There is a new comment on your website: http://example.com' ); } ?>

Notice that you are using the comment_post Action hook. This action is triggered whenever a new comment is posted in WordPress. As you can see, the prowp_email_new_comment() function will send an e-mail any time a new comment is created. Also notice that you are not sending in any

c08.indd 152 12/6/12 1:19 AM Know Your Hooks: Actions and Filters ❘ 153

variables to your function or returning any values out of your function. Action hooks don’t require this, but if needed, you can pass values into your function.

Popular Filter Hooks More than 1,500 different hooks are available in WordPress, which is a bit overwhelming at fi rst. Fortunately, a handful of them are used much more often than the rest. This section explores some of the more commonly used hooks in WordPress. Some of the more common Filter hooks are:

➤ the_content — Applied to the content of the post or page before displaying ➤ the_content_rss — Applied to the content of the post or page for RSS inclusion ➤ the_title — Applied to the post or page title before displaying ➤ comment_text — Applied to the comment text before displaying ➤ wp_title — Applied to the page before displaying ➤ the_permalink — Applied to the permalink URL Let’s look at some of the more popular Filter hooks in WordPress, starting with a more practical example than your profanity fi lter, which uses the_content Filter hook. This hook allows you to alter the content for posts and pages prior to it being displayed in the browser. By using this hook you can add your custom content either before, in the middle, or after the content: <?php add_filter ( 'the_content', 'prowp_subscriber_footer' ); function prowp_subscriber_footer( $content ) { if( is_single() ) {$content.= '<h3>Enjoyed this article?</h3>'; $content.= 'Subscribe to my <a href="http://example.com/feed">RSS feed</a>!'; } return $content; } ?> In this example, you are adding your subscribe text to the bottom of the content of your posts. Notice that you are also using the is_single() conditional tag to verify that your subscribe text is added only on a single post page. The $content variable stores all of the post or page content, so by appending your subscribe text you are adding it to the bottom of your post content. This is the ideal way to add content to the bottom of all posts because you aren’t actually modifying the post. In the future, if you decide to change this message you can change it in one place, rather than updating every post in your website. c08.indd 153 12/6/12 1:19 AM 154 ❘ CHAPTER 8 PLUGIN DEVELOPMENTAnother powerful Filter hook is the_title. This hook is used for changing the post or page title prior to being displayed. Here’s an example that uses this fi lter: <?php add_filter( 'the_title', 'prowp_custom_title' ); function prowp_custom_title( $title ) {$title .= ' - By Example.com'; return $title;} ?> This example adds “By Example.com” to all of your post and page titles. Remember that this doesn’t actually modify the title in the database but instead modifi es the display of the title generated for the end user.The default_content Filter hook is useful for setting the default content when creating a new post or page. This is helpful if you have a set format for all of your posts as it can save you valuable writing time: <?php add_filter( 'default_content', 'prowp_default_content' ); function prowp_default_content( $content ) {$content = 'For more great content please subscribe to my RSS feed'; return $content;} ?> Filter hooks are exceptionally powerful for inserting your own processing into a variety of points in the Loop processing of each post. Realizing the full power of the WordPress plugin system means also using action hooks to fi re your own code in response to events within the WordPress core.Popular Action Hooks Some of the more common Action hooks are:➤ publish_post — Triggered when a new post is published. ➤ create_category — Triggered when a new category is created. ➤ switch_theme — Triggered when you switch themes. ➤ admin_head — Triggered in the <head> section of the admin dashboard. ➤ wp_head — Triggered in the <head> section of your theme. ➤ wp_footer — Triggered in the footer section of your theme usually directly before the </body> tag. ➤ init — Triggered after WordPress has fi nished loading, but before any headers are sent. Good place to intercept $_GET and $_POST HTML requests. c08.indd 154 12/6/12 1:19 AM Know Your Hooks: Actions and Filters ❘ 155➤ admin_init: Same as init but only runs on admin dashboard pages. ➤ user_register: Triggered when a new user is created. ➤ comment_post: Triggered when a new comment is created.One of the most commonly used Action hooks is the wp_head hook. Using the wp_head hook, you can insert any custom code into the <head> section of the WordPress theme. Consider the following example: <?php add_action( 'wp_head', 'prowp_custom_css' ); function prowp_custom_css() { ?> <style type="text/css"> a { font-size: 14px; color: #000000; text-decoration: none; } a:hover { font-size: 14px color: #FF0000; text-decoration: underline; } </style> <?php } ?>This code will drop anything inside your prowp_custom_css() function into the header of the WordPress theme, in this case your custom CSS script.The wp_footer hook is also a very commonly used Action hook. Using this hook you can insert any custom code in the footer of the WordPress theme. This is a great method for adding analytic tracking code to your website: <?php add_action( 'wp_footer', 'prowp_site_analytics' ); function prowp_site_analytics() { ?> <script type="text/javascript"> var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); document.write(unescape("%3Cscript src='" + gaJsHost + 'google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); </script> <script type="text/javascript"> var pageTracker = _gat._getTracker("UA-XXXXXX-XX"); pageTracker._trackPageview(); </script> <?php } ?> c08.indd 155 12/6/12 1:19 AM 156 ❘ CHAPTER 8 PLUGIN DEVELOPMENTIn the preceding example you can see how you can easily insert your Google Analytics tracking code to the footer of every page on your website.The admin_head Action hook is very similar to the wp_head hook, but rather than hooking into the theme header, it hooks into the admin dashboard header. This is useful if your plugin requires custom CSS on the admin dashboard, or any other custom header code.The user_register Action hook is executed when a new user is created in WordPress. This user can be created by an admin or by the new user. This is a useful hook if you want to set some default values for a new user or to e-mail your new members thanking them for joining your website. Hooks are probably one of the most under-documented features in WordPress. It can be a real challenge fi nding the correct hooks to use for the job. The fi rst resource to use is always the Codex. Here you can fi nd the Filter Reference (http://codex.wordpress.org/Plugin_API/ Filter_Reference) and Action Reference (http://codex.wordpress.org/Plugin_API/Action_ Reference) sections helpful in tracking down appropriate hooks.Another highly recommended reference is the Plugin Directory (http://wordpress.org/extend/ plugins/) on WordPress.org. Sometimes the best way to fi gure something out is to see how other developers accomplished a similar task. Find a plugin in the directory that is similar in functionality to what you want to build. Most likely, the plugin author will have already dug up the correct hooks for WordPress that you will be using. It never hurts to learn by example, and published plugins are the perfect examples in this case!PLUGIN SETTINGSMost plugins feature a settings page. This helps users confi gure the plugin to act in different ways without actually modifying the code behind the plugin by saving various option settings. The fi rst step in this process is saving and retrieving options in WordPress.Saving Plugin Options Chances are that, when building a plugin, you will need to save some options for your plugin. WordPress features some very easy-to-use functions to save, edit, and delete options. Two functions are available for creating options: add_option() and update_option(). Both functions create options, but update_option() also updates the option if it already exists. Here’s an example of adding a new option: <?php add_option( 'prowp_display_mode', 'Fright Night' ); ?>The fi rst parameter you send to the add_option() function is the name of your option. This is a required fi eld and must be unique from all other options saved in WordPress, including from other plugins. The second parameter is the option value. This is also a required fi eld and can be a string, an array, an object, or a serialized value. You can also use update_option() to create new options. This function checks whether the option exists fi rst, and if not creates it. If, however, the option already exists, it updates the value with the new option value you are sending in. You call the update_option() function exactly as you did when adding an option like so: <?php update_option( 'prowp_display_mode', 'Fright Night' ); ?> c08.indd 156 12/6/12 1:19 AM Plugin Settings ❘ 157Generally, the update_option() function is used for both adding and updating options in plugins. It’s much easier to stay consistent with one function call for both rather than calls to different functions for adding and updating your plugin options.Retrieving an option value is just as easy. To retrieve any option, use the get_option() function, as shown here: <?php echo get_option( 'prowp_display_mode' ); ?>The only required fi eld for get_option() is the name of the option you want to retrieve. If the option exists, it is returned to display or it is stored in a variable. If the option doesn’t exist, the function returns FALSE.Options can be deleted as easily as they are created. To delete an option, use the delete_option() function. The only parameter is the option name that you want to delete: <?php delete_option( 'prowp_display_mode' ); ?>A good rule of thumb is to start all of your option names with the same prefi x, like prowp_ in the preceding examples. This is useful for a couple of reasons: uniqueness and readability. Using a prefi x will help validate the uniqueness of your option names. If you have a number of options, it is a smart idea to store them in an array (see the next section). This also makes it much easier to follow your code logic when there is a set naming convention used on variables, functions, and so on. Options in WordPress are not reserved for just plugins. Themes can also create options to store specifi c theme data. Many of the themes available today offer a settings page, enabling you to customize the theme through settings rather than code.Array of Options Every option you create in WordPress adds a new record to the wp_options database table. Because of this, it’s a smart idea to store your options in an array, thus creating fewer records in the database and fewer update_option() calls you need to make. <?php $prowp_options_arr = array( 'prowp_display_mode' => 'Fright Night', 'prowp_default_browser' => 'Chrome', 'prowp_favorite_book' => 'Professional WordPress', ); update_option( 'prowp_plugin_options', $prowp_options_arr ); ?> In this code, you are creating an array to store your plugin option values. So rather than call update_option() three times, and save three records in the database, you need to call it only once and save your array to the option named prowp_plugin_options. This is a small example but imagine a collection of plugins that store 50 options to the database’s options table. That would really start to clutter up your options table and would most likely slow down your website load speeds due to the repeated database query options to fetch or set those options individually. c08.indd 157 12/6/12 1:19 AM 158 ❘ CHAPTER 8 PLUGIN DEVELOPMENTTo retrieve the array of options, you use the same get_option() function as before: <?php $prowp_options_arr = get_option( 'prowp_plugin_options' );$prowp_display_mode = $prowp_options_arr['prowp_display_mode']; $prowp_default_browser = $prowp_options_arr['prowp_default_browser']; $prowp_favorite_book = $prowp_options_arr['prowp_favorite_book']; ?> The next section discusses how to create a menu for your plugin settings page.Creating a Menu and Submenus WordPress features two different ways to create a custom menu for your plugin. The fi rst thing you’ll want to decide is where to locate your options page. The options page link can be located in its own top-level menu (My Plugin Settings), or as a submenu item of an existing menu (Settings ➪ My Plugin Settings). This section explores both methods and how to confi gure each.Creating a Top-Level Menu The fi rst method you’ll explore is creating a new top-level menu. Using a top-level menu is useful if your plugin has multiple settings pages that need to be separate. To create your own top-level menu, you’ll use the add_menu_page function, as shown here: <?php add_menu_page( page_title, menu_title, capability, menu_slug, function, icon_url, position ); ?> Here’s a breakdown of the parameters allowed:➤ page_title — Text used for the HTML title (between <title> tags). ➤ menu_title — Text used for the menu name in the Dashboard. ➤ capability — Minimum user capability required to see menu. ➤ menu_slug — Unique slug name for your menu. ➤ function — Displays page content for the menu settings page. ➤ icon_url — Path to custom icon for menu (default: images/generic.png). ➤ position — The position in the menu order the menu should appear. By default, the menu will appear at the bottom of the menu structure.You can also create submenu items for your new menu. You use the add_submenu_page() function to create additional submenu items: add_submenu_page( parent, page_title, menu_title, capability, menu_slug,[function] ); Create a custom menu for a plugin with multiple submenu items, as shown in Figure 8-3. c08.indd 158 12/6/12 1:19 AM Plugin Settings ❘ 159<?php // create custom plugin settings menu add_action( 'admin_menu', 'prowp_create_menu' ); function prowp_create_menu() {//create new top-level menu add_menu_page( 'Halloween Plugin Page', 'Halloween Plugin', 'manage_options', 'prowp_main_menu', 'prowp_main_plugin_page', plugins_url( '/images/wordpress.png', __FILE__ ) );//create two sub-menus: settings and support add_submenu_page( 'prowp_main_menu', 'Halloween Settings Page', 'Settings', 'manage_options', 'halloween_settings', 'prowp_settings_page' ); add_submenu_page( 'prowp_main_menu', 'Halloween Support Page', 'Support', 'manage_options', 'halloween_support', 'prowp_support_page' );} ?>First you call the admin_menu Action hook. This hook is triggered after the basic admin panel menu structure is in place. Once triggered, you call your custom function prowp_create_menu() to build your menu.To create your menu, you call the add_menu_page() function. The fi rst two parameters set your page title and menu title. You also set the capability level to manage_options so only an admin will see this new menu. Next, you set the menu slug to propwp_main_menu, which is the unique slug for your menu. Your custom menu function name is next, in this case prowp_main_ FIGURE 8-3: Custom plugin_page. Remember that you haven’t created this function yet so when top-level menu viewing the settings page, you will get a PHP warning. Finally, you set the custom icon location to display the WordPress logo. Now that you’ve created your top-level menu, you need to create your submenu items. In this example, you are creating two submenu items: Settings and Support. To do this, you use the add_submenu_page() function. The fi rst parameter you send is the menu slug of the top-level menu you want this to fall under. Remember that you set this to prowp_main_menu, which is a unique slug for your plugin menu. Next, you set the page title and menu title just like before. You also set the access level for viewing to manage_options. You also have to create a unique menu slug for your submenu items; in this example, you’ll use a custom named value, halloween_settings and halloween_support. The fi nal value is the custom function to build the settings page for each submenu.Adding to an Existing Menu Next, you’ll explore how to add a submenu item to an existing menu in WordPress. Most plugins have only one options page and therefore do not require an entirely separate top-level menu. To c08.indd 159 12/6/12 1:19 AM 160 ❘ CHAPTER 8 PLUGIN DEVELOPMENT accomplish this, you can add a plugin option page to any existing menu in WordPress. Add a submenu to the Setting menu: <?php add_action( 'admin_menu', 'prowp_create_settings_submenu' ); function prowp_create_settings_submenu() { add_options_page( 'Halloween Settings Page', 'Halloween Settings', 'manage_options', 'halloween_settings_menu', 'prowp_settings_page' ); } ?> WordPress features multiple functions to make adding submenus extremely easy. To add your Halloween Settings submenu you use the add_options_page() function. The fi rst parameter is the page title followed by the submenu display name. Like your other menus, you set the capability to manage_options, so the menu is viewable only by administrators. Next, you set the unique menu handle to halloween_settings_menu. Finally, you call your custom prowp_settings_page() function to build your options page. The preceding example adds your custom submenu item Halloween Settings at the bottom of the settings menu. Following is a list of the available submenu functions in WordPress. Each function can be used exactly as the preceding example; just swap out the function name called with one of the functions listed here:➤ add_dashboard_page() — Adds submenu items to the Dashboard menu ➤ add_posts_page() — Adds submenu items to the Posts menu ➤ add_media_page() — Adds a submenu item to the Media menu ➤ add_links_page() — Adds a submenu item to the Links menu ➤ add_pages_page() — Adds a submenu item to the Pages menu ➤ add_comments_page() — Adds a submenu item to the Comments menu ➤ add_plugins_page() — Adds a submenu item to the Plugins menu ➤ add_theme_page() — Adds a submenu item to the Appearance menu ➤ add_users_page() — Adds a submenu item to the Users page (or Profi le based on role) ➤ add_management_page() — Adds a submenu item to the Tools menu ➤ add_options_page() — Adds a submenu item to the Settings menuNow that you’ve created your menu and submenu items, you need to create an options page to display your plugin confi guration.Creating an Options Page WordPress 2.7 introduced a new Settings API that you will be using for all of the option methods you use in this section. The Settings API is a powerful set of functions to help make saving options in WordPress easy and secure. One of the major benefi ts of the Settings API is that WordPress handles the security checks, meaning you don’t need to include a nonce in your form. c08.indd 160 12/6/12 1:19 AM Plugin Settings ❘ 161The fi rst option page method you’ll explore is to create a unique option page for your top-level menu. Remember that when using the add_menu_page() and add_submenu_page() functions, you defi ned your menu item function name to display your options page. To create an options page, you need to create this function to display your options. First set up your plugin menu: <?php// create custom plugin settings menu add_action( 'admin_menu', 'prowp_create_menu' ); function prowp_create_menu() {//create new top-level menu add_menu_page( 'Halloween Plugin Page', 'Halloween Plugin', 'manage_options', 'prowp_main_menu', 'prowp_settings_page', plugins_url( '/images/wordpress.png', __FILE__ ) );//call register settings function add_action( 'admin_init', 'prowp_register_settings' );} ?>Notice that you’ve added a new Action hook for admin_init to execute your prowp_register_ settings() function, as shown in the following code: <?php function prowp_register_settings() {//register our settings register_setting( 'prowp-settings-group', 'prowp_options', 'prowp_sanitize_options' );}?>Using the Setting API’s register_setting() function, you defi ne the option you are going to offer on your plugin options page. Your settings page will have three options, but you are going to store those three options in a single options array, so you only need to register a single setting here. The fi rst parameter is the options group name. This required fi eld needs to be a group name to identify all options in this set. The second parameter is the actual option name and must be unique. The third parameter is a callback function to sanitize the option values. Now that you’ve registered your options, you need to build your options page. To do so, you’ll create the prowp_settings_page() function as called from your menu: <?php function prowp_settings_page() { ?> <div class="wrap"> <h2>Halloween Plugin Options</h2><form method="post" action="options.php"> <?php settings_fields( 'prowp-settings-group' ); ?> <?php $prowp_options = get_option( 'prowp_options' ); ?> <table class="form-table"> c08.indd 161 12/6/12 1:19 AM 162 ❘ CHAPTER 8 PLUGIN DEVELOPMENT<tr valign="top"> <th scope="row">Name</th> <td><input type="text" name="prowp_options[option_name]" value="<?php echo esc_attr( $prowp_options['option_name'] ); ?>" /> </td> </tr><tr valign="top"> <th scope="row">Email</th> <td><input type="text" name="prowp_options[option_email]" value="<?php echo esc_attr( $prowp_options['option_email'] ); ?>" /></td> </tr><tr valign="top"> <th scope="row">URL</th> <td><input type="text" name="prowp_options[option_url]" value="<?php echo esc_url( $prowp_options['option_url'] ); ?>" /> </td> </tr> </table> <input type="submit" class="button-primary" value="Save Changes" /> </form> </div> <?php } ?>As you can see, this looks like a standard form with a couple of noticeable differences. The <form> tag must be set to post to options.php. Inside your form, you need to defi ne your settings group, which you set to prowp-settings-group when you registered your settings. This establishes the link between your options and their values. You do so with this line of code: <?php settings_fields( 'prowp-settings-group' ); ?>Next, you’ll load the existing options array, if there are any, to the $prowp_options variable using the get_option() function. You’ll use this variable to display the existing options that are set in your form. Then you build the table to display your form options. Notice the name of the form fi eld needs to be in the format of option_name[field_name]. This is because you are storing all option values in a single array. <input type="text" name="prowp_options[option_email]" value="<?php echo esc_attr( $prowp_options['option_email'] ); ?>" /> After you have displayed all of your form fi elds, you need to display a Submit button to post the form and save your options. The fi nal step is to create the prowp_sanitize_options() function. This function will be used to sanitize all data submitted in your plugin settings prior to saving in the c08.indd 162 12/6/12 1:19 AM Plugin Settings ❘ 163 database. This is an extremely important step because unsanitized data could potentially open up a security vulnerability in your plugin. <?php function prowp_sanitize_options( $input ) {$input['option_name'] = sanitize_text_field( $input['option_name'] ); $input['option_email'] = sanitize_email( $input['option_email'] ); $input['option_url'] = esc_url( $input['option_url'] ); return $input;} ?> Notice how each option value is being sanitized with a specifi c function. The name option uses the WordPress function sanitize_text_field() to strip any HTML, XML, and PHP tags from the submitted value. You use the sanitize_email() WordPress function to sanitize the e-mail value and esc_url() to sanitize the URL value. That’s it! You have just created a very basic plugin options page using the Settings API in WordPress. Listing 8-1 shows the entire code to build an options page.LISTING 8-1: Building the Options Page (prowp2-settings-api-plugin.zip)<?php // create custom plugin settings menu add_action( 'admin_menu', 'prowp_create_menu' ); function prowp_create_menu() {//create new top-level menu add_menu_page( 'Halloween Plugin Page', 'Halloween Plugin', 'manage_options', 'prowp_main_menu', 'prowp_settings_page', plugins_url( '/images/wordpress.png', __FILE__ ) );//call register settings function add_action( 'admin_init', 'prowp_register_settings' );} function prowp_register_settings() {//register our settings register_setting( 'prowp-settings-group', 'prowp_options', 'prowp_sanitize_options' );} function prowp_sanitize_options( $input ) {$input['option_name'] = sanitize_text_field( $input['option_name'] ); continues c08.indd 163 12/6/12 1:19 AM 164 ❘ CHAPTER 8 PLUGIN DEVELOPMENTLISTING 8-1 (continued)$input['option_email'] = sanitize_email( $input['option_email'] ); $input['option_url'] = esc_url( $input['option_url'] ); return $input;} function prowp_settings_page() { ?> <div class="wrap"> <h2>Halloween Plugin Options</h2><form method="post" action="options.php"> <?php settings_fields( 'prowp-settings-group' ); ?> <?php $prowp_options = get_option( 'prowp_options' ); ?> <table class="form-table"> <tr valign="top"> <th scope="row">Name</th> <td><input type="text" name="prowp_options[option_name]" value="<?php echo esc_attr( $prowp_options['option_name'] );?> " /></td> </tr><tr valign="top"> <th scope="row">Email</th> <td><input type="text" name="prowp_options[option_email]" value="<?php echo esc_attr( $prowp_options['option_email'] ); ?> " /></td> </tr><tr valign="top"> <th scope="row">URL</th> <td><input type="text" name="prowp_options[option_url]" value="<?php echo esc_url( $prowp_options['option_url'] ); ?>" /> </td> </tr> </table> <input type="submit" class="button-primary" value="Save Changes" /> </form> </div> <?php } ?>The second option page method is to add your plugin settings to an existing Settings page in WordPress, as shown in Figure 8-4. You will also be using the WordPress Settings API functions to hook into these pages and add your plugin settings. c08.indd 164 12/6/12 1:19 AM Plugin Settings ❘ 165FIGURE 8-4: Custom settings sectionNow look over at the code to create your custom settings section. In the following example, you are going to add a new settings section at the bottom of the Settings ➪ Reading Settings page. This section will contain options for your plugin. <?php //execute our settings section function add_action( 'admin_init', 'prowp_settings_init' ); function prowp_settings_init() {//create the new setting section on the Settings > Reading page add_settings_section( 'prowp_setting_section', 'Halloween Plugin Settings', 'prowp_setting_section', 'reading' );// register the individual setting options add_settings_field( 'prowp_setting_enable_id', 'Enable Halloween Feature?', 'prowp_setting_enabled', 'reading', 'prowp_setting_section' ); add_settings_field( 'prowp_saved_setting_name_id', 'Your Name', 'prowp_setting_name', 'reading', 'prowp_setting_section' );// register the setting to store our array of values register_setting( 'reading', 'prowp_setting_values' );} ?> c08.indd 165 12/6/12 1:19 AM 166 ❘ CHAPTER 8 PLUGIN DEVELOPMENTFirst, you use the admin_init Action hook to load your custom function prowp_settings_init() before any admin page is rendered. Next, you call the add_settings_section() function to create your new section: <?php add_settings_section( 'prowp_setting_section', 'Halloween Plugin Settings', 'prowp_setting_section', 'reading' ); ?> The fi rst parameter passed is a unique ID for the section. The second parameter is the display name output on the page. Next, you pass in the callback function name to display the actual section itself. The fi nal parameter sets what settings page to add your section to. The accepted default WordPress values are general, writing, reading, discussion, media, privacy, and permalink. <?php // register the individual setting options add_settings_field( 'prowp_setting_enable_id', 'Enable Halloween Feature?', 'prowp_setting_enabled', 'reading', 'prowp_setting_section' ); add_settings_field( 'prowp_saved_setting_name_id', 'Your Name', 'prowp_setting_name', 'reading', 'prowp_setting_section' ); ?> Now that you’ve registered your custom settings section, you need to register your individual setting options. To do this, you’ll be using the add_settings_field() function. The fi rst parameter you are passing is a unique ID for the fi eld. Next, you pass in the title of the field, which is displayed directly to the left of the option fi eld. The third parameter is the callback function name, which you’ll use to display your option fi eld. The fourth parameter is the settings page where the fi eld should be displayed. The fi nal parameter is the name of the section you are adding the fi eld to, which in this example is the prowp_setting_section you created with the add_setting_ section() function call. <?php register_setting( 'reading', 'prowp_setting_values', 'prowp_sanitize_settings' ); ?> Next, you need to register your setting fi eld. In this example, you are going to register two different settings: one for an enable/disable check box and one for the user’s name. Even though you have two setting fi elds, you are going to store both values in an array, so you only need to register one setting called prowp_setting_values. The fi rst parameter you pass is the option group. In this example, you are saving your options in the reading group with the rest of the reading options. The second parameter is the option name. The option name should be unique and is used to retrieve the value of the option. A third optional parameter can be set for a custom function used to sanitize the option values. In this example, you’ll create a function called prowp_sanitize_settings() to sanitize the option values entered by the user. <?php function prowp_sanitize_settings( $input ) {$input['enabled'] = ( $input['enabled'] == 'on' ) ? 'on' : ''; c08.indd 166 12/6/12 1:19 AM Plugin Settings ❘ 167$input['name'] = sanitize_text_field( $input['name'] ); return $input;} ?> As always, you’ll want to sanitize all option values that are entered by the user. The enabled option is a check box, and therefore can only be one of two values: either checked or not. The preceding example uses a PHP ternary operator to determine the value of Enabled. If the check box equals “on,” you know the value is enabled and should save the option value as “on.” If not, the option will save the value as empty, which means the check box is not checked. Now that you’ve registered your setting section, you need to create your custom functions to display it. The fi rst function you’ll create is the prowp_setting_section() that you called in when you created your setting section: <?php function prowp_setting_section() { echo 'Configure the Halloween plugin options below'; } ?> This is where you can set the subheading for your settings section. This section is great for plugin instructions, confi guration information, and more. Next, you need to create the function to display your fi rst settings fi eld, Enabled: <?php function prowp_setting_enabled() {//load plugin options $prowp_options = get_option( 'prowp_setting_values' );//display the checkbox form field echo '<input '.checked( $prowp_options['enabled'], 'on', false ).' name="prowp_setting_values[enabled]" type="checkbox" /> Enabled';} ?>This is the callback function you defi ned when you used the add_settings_field() function. The fi rst step is to load the options array if it exists. Because this option is a check box, you know that if it is set, the check box should be checked. In this example, you’ll use the checked() WordPress function. This function has three parameters. The fi rst and second parameters are two values to compare. If the two values are the same, the function will echo checked="checked" thus checking the form element. The third parameter determines whether to echo the value or just return it. In this case, you just want to return it so you set that value to False. Next, you display the actual setting fi eld that will be used in the setting section. Your fi eld input name needs to be the same setting name you registered previously. Because you are saving your options as an array, you need to defi ne the array name value; in this example, it’s prowp_ setting_values[enabled]. This is how the Settings API knows what option to save and where. c08.indd 167 12/6/12 1:19 AM 168 ❘ CHAPTER 8 PLUGIN DEVELOPMENTYour Enabled check box fi eld will display at the bottom of the Settings ➪ Reading page. Now you need to create the function for your second setting fi eld: <?php function prowp_setting_name() {//load the option value $prowp_options = get_option( 'prowp_setting_values' );//display the text form field echo '<input type="text" name="prowp_setting_values[name]" value="'.esc_attr( $prowp_options['name'] ).'" />';} ?> As with your check box option, the fi rst thing to do is load the current option value. Then you display your input text fi eld with the same name as defi ned previously in the register_setting() function. As always, be sure to escape the value before displaying in the form fi eld. That’s it! You have successfully created your custom settings section and added it to the Settings ➪ Reading SubPanel. Listing 8-2 shows the full code.LISTING 8-2: Custom Settings Section (prowp2-reading-settings-plugin.zip)<?php//execute our settings section function add_action( 'admin_init', 'prowp_settings_init' ); function prowp_settings_init() {//create the new setting section on the Settings > Reading page add_settings_section( 'prowp_setting_section', 'Halloween Plugin Settings', 'prowp_setting_section', 'reading' );// register the individual setting options add_settings_field( 'prowp_setting_enable_id', 'Enable Halloween Feature?', 'prowp_setting_enabled', 'reading', 'prowp_setting_section' ); add_settings_field( 'prowp_saved_setting_name_id', 'Your Name', 'prowp_setting_name', 'reading', 'prowp_setting_section' );// register the setting to store our array of values register_setting( 'reading', 'prowp_setting_values', 'prowp_sanitize_settings' );} function prowp_sanitize_settings( $input ) {$input['enabled'] = ( $input['enabled'] == 'on' ) ? 'on' : ''; c08.indd 168 12/6/12 1:19 AM WordPress Integration ❘ 169$input['name'] = sanitize_text_field( $input['name'] ); return $input;}// settings section function prowp_setting_section() { echo 'Configure the Halloween plugin options below'; }// create the enabled checkbox option to save the checkbox value function prowp_setting_enabled() {//load plugin options $prowp_options = get_option( 'prowp_setting_values' );//display the checkbox form field echo '<input '.checked( $prowp_options['enabled'], 'on', false ) .' name="prowp_setting_values[enabled]" type="checkbox" /> Enabled';}// create the text field setting to save the name function prowp_setting_name() {//load the option value $prowp_options = get_option( 'prowp_setting_values' );//display the text form field echo '<input type="text" name="prowp_setting_values[name]" value="'.esc_attr( $prowp_options['name'] ).'" />';} ?>WORDPRESS INTEGRATIONIntegrating your plugin into WordPress is an essential step for users to interact with your plugin in the admin dashboard. WordPress features many different areas where your plugin can be integrated, including a meta box, sidebar, and dashboard widgets, and custom shortcodes.Creating a Meta Box WordPress features multiple meta boxes on the Add New Post and Page screens. These meta boxes are used for adding additional information to your posts, pages, and content.Meta boxes can be created in a plugin using the add_meta_box() function in WordPress. This function accepts seven parameters, as shown here: <?php add_meta_box( $id, $title, $callback, $page, $context, $priority, $callback_args ); ?> c08.indd 169 12/6/12 1:19 AM 170 ❘ CHAPTER 8 PLUGIN DEVELOPMENTEach parameter helps defi ne where and how your meta box is displayed.➤ $id: The CSS ID attribute for the meta box ➤ $title: The title displayed in the header of the meta box ➤ $callback: The custom function name to display your meta box information ➤ $page: The page you want your meta box to display on ('post', 'page',, or custom post type name) ➤ $context: The part of the page where the meta box should be displayed ('normal', 'advanced', or 'side') ➤ $priority: The priority within the context where the meta box should display ('high', 'core', 'default', or 'low') ➤ $callback_args: Arguments to pass into your callback function Now that you understand the add_meta_box() function, you can build your fi rst custom meta box in WordPress: <?php add_action( 'add_meta_boxes', 'prowp_meta_box_init' );// meta box functions for adding the meta box and saving the data function prowp_meta_box_init() {// create our custom meta box add_meta_box( 'prowp-meta', 'Product Information', 'prowp_meta_box', 'post', 'side', 'default' );} ?>The fi rst step to adding your own meta box is to use theadd_meta_boxes Action hook to execute your custom function prowp_meta_box_init(). In this function, you will call the add_meta_box() function to create your custom meta box for Product Information. You set the CSS ID attribute to prowp-meta for your meta box. The second parameter is the title, which you set to Product Information. The next parameter is your custom function prowp_meta_ box(), which will display the HTML for your meta box. Next you defi ne your meta box to display on the post page and in the sidebar. Finally, you set the priority to default. Now create your custom prowp_meta_box() function to display your meta box fi elds: function prowp_meta_box( $post, $box ) {// retrieve the custom meta box values $prowp_featured = get_post_meta( $post->ID, '_prowp_type', true ); $prowp_price = get_post_meta( $post->ID, '_prowp_price', true );//nonce for security wp_nonce_field( plugin_basename( __FILE__ ), 'prowp_save_meta_box' );// custom meta box form elements echo 'Price: <input type="text" name="prowp_price" c08.indd 170 12/6/12 1:19 AM WordPress Integration ❘ 171 value="'.esc_attr( $prowp_price ).'" size="5" />'; echo 'Type: <select name="prowp_product_type" id="prowp_product_type"> <option value="0" ' .selected( $prowp_featured, 'normal', false ). '>Normal </option> <option value="special" ' .selected( $prowp_featured, 'special', false ). '>Special </option> <option value="featured" ' .selected( $prowp_featured, 'featured', false ). '>Featured </option> <option value="clearance" ' .selected( $prowp_featured, 'clearance', false ). '>Clearance </option> </select>';} The fi rst step in your custom function is to retrieve the saved values for your meta box. If you are creating a new post, there won’t be any saved values yet. Next you display the form elements in your meta box. Notice that you don’t need any <form> tags or a submit button. Also notice that you are using the wp_nonce_field() function to create a custom nonce fi eld in your form. The custom function you just created will generate your custom meta box, as shown in Figure 8-5. Now that you have your meta box and form elements, you need to save that data when your post is saved. To do so, you’ll create a custom function, prowp_save_meta_box(), which is triggered by FIGURE 8-5: Custom meta the save_post Action hook: box <?php // hook to save our meta box data when the post is saved add_action( 'save_post', 'prowp_save_meta_box' ); function prowp_save_meta_box( $post_id ) {// process form data if $_POST is set if( isset( $_POST['prowp_product_type'] ) ) {// if auto saving skip saving our meta box data if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;//check nonce for security check_admin_referer( plugin_basename( __FILE__ ), 'prowp_save_meta_box' );// save the meta box data as post meta using the post ID as a unique prefix update_post_meta( $post_id, '_prowp_type', sanitize_text_field( $_POST['prowp_product_type'] ) ); update_post_meta( $post_id, '_prowp_price', c08.indd 171 12/6/12 1:19 AM 172 ❘ CHAPTER 8 PLUGIN DEVELOPMENT sanitize_text_field ( $_POST['prowp_price'] ) );}} ?>The save_post Action hook runs whenever a post is saved in WordPress. Because you only want to work with the custom metadata in the meta box, the fi rst thing you’ll do is verify that the $_POST['prowp_product_type'] value is set. Next, you need to verify that the post being saved is an active post and not an auto save. To do so, you check that the post is not auto-saving and, if so, you exit the function. The next step is to verify that the nonce value is the expected value. If the post is active and your form elements have been set, you save the form data. Once all checks have passed, you use update_post_meta() to save your meta box data as metadata against your post.As you can see, you send in the post ID as the fi rst parameter to update_post_meta(). This tells WordPress what post the meta data will be attached to. Next, you pass in the name of the meta key you are updating. Notice the meta key name is prefi xed with an underscore. This prevents these values from being listed in the custom fi elds meta box on the post edit screen. Because you’ve provided a UI to edit these values, you don’t need them in the custom fi elds box. The fi nal parameter you send is the new value for the meta key, which is being sanitized using the sanitize_text_field() WordPress function. You now have a fully functional custom meta box that saves individual data against each post. Listing 8-3 shows the full custom meta box code.LISTING 8-3: Custom Meta Box (prowp2-custom-meta-box.zip)<?php add_action( 'add_meta_boxes', 'prowp_meta_box_init' );// meta box functions for adding the meta box and saving the data function prowp_meta_box_init() {// create our custom meta box add_meta_box( 'prowp-meta', 'Product Information', 'prowp_meta_box', 'post', 'side', 'default' );} function prowp_meta_box( $post, $box ) {// retrieve the custom meta box values $prowp_featured = get_post_meta( $post->ID, '_prowp_type', true ); $prowp_price = get_post_meta( $post->ID, '_prowp_price', true );//nonce for security wp_nonce_field( plugin_basename( __FILE__ ), 'prowp_save_meta_box' );// custom meta box form elements echo 'Price: <input type="text" name="prowp_price" value="'.esc_attr( $prowp_price ).'" size="5" />'; c08.indd 172 12/6/12 1:19 AM WordPress Integration ❘ 173 echo 'Type: <select name="prowp_product_type" id="prowp_product_type"> <option value="0" ' .selected( $prowp_featured, 'normal', false ) . '>Normal</option> <option value="special" ' .selected( $prowp_featured, 'special', false ) . '>Special</option> <option value="featured" ' .selected( $prowp_featured, 'featured', false ) . '>Featured</option> <option value="clearance" ' .selected( $prowp_featured, 'clearance', false ) . '>Clearance</option> </select>';}// hook to save our meta box data when the post is saved add_action( 'save_post', 'prowp_save_meta_box' ); function prowp_save_meta_box( $post_id ) {// process form data if $_POST is set if( isset( $_POST['prowp_product_type'] ) ) {// if auto saving skip saving our meta box data if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;//check nonce for security check_admin_referer( plugin_basename( __FILE__ ), 'prowp_save_meta_box' );// save the meta box data as post meta using the post ID as a unique prefix update_post_meta( $post_id, '_prowp_type', sanitize_text_field( $_POST['prowp_product_type'] ) ); update_post_meta( $post_id, '_prowp_price', sanitize_text_field( $_POST['prowp_price'] ) );}} ?> Now that you’ve saved your meta box data, you’ll probably want to display it somewhere. You can easily display your saved meta box data in your theme using the get_post_meta function inside the Loop like so: <?php $prowp_type = get_post_meta( $post->ID, '_prowp_type', true ); $prowp_price = get_post_meta( $post->ID, '_prowp_price', true ); echo 'Price: ' .esc_html( $prowp_price ). ''; echo 'Type: ' .esc_html( $prowp_type ). ''; ?> c08.indd 173 12/6/12 1:19 AM 174 ❘ CHAPTER 8 PLUGIN DEVELOPMENTAdding a custom meta box is a great way to extend the data on posts and pages and is very intuitive for users as well.Shortcodes WordPress features a Shortcode API that can be used to easily create shortcode functionality in your plugins. Shortcodes are basically text macro codes that can be inserted into a post, page, or custom post type. When being displayed, these shortcodes are replaced by some other type of content. Look at a simple example using the Shortcode API: <?php add_shortcode( 'mytwitter', 'prowp_twitter' ); function prowp_twitter() { return '<a href="http://twitter.com/williamsba">@williamsba</a>';} ?>Now any time you use the [mytwitter] shortcode in your content, it will be replaced with an HTML link to my Twitter account when displayed in the browser. As you can see, this is a very powerful feature in WordPress, which many plugins out there currently take advantage of, often inserting small pieces of JavaScript to place a button or advertisement in the specifi c spot in a post. Shortcodes can also be confi gured to accept attributes. This is very useful for passing arguments to your custom functions, thereby altering the output of the shortcode based on those arguments. Modify your shortcode function to accept a site parameter: <?php add_shortcode( 'mytwitter', 'prowp_twitter' ); function prowp_twitter( $atts, $content = null ) { extract( shortcode_atts( array( 'person' => 'brad' // set attribute default ), $atts ) ); if ( $person == 'brad' ) { return '<a href="http://twitter.com/williamsba">@williamsba</a>'; }elseif ( $person == 'david' ) { return '<a href="http://twitter.com/mirmillo">@mirmillo</a>'; }elseif ( $person == 'hal' ) { return '<a href="http://twitter.com/freeholdhal">@freeholdhal</a>'; } } ?> This code creates the same shortcode as before, but now you are defi ning an attribute called person. With this attribute, you can specify which person you want to display a Twitter link for. To display the Twitter URL for David, you would use the shortcode[mytwitter person="david"]. Alternatively, you can also easily display the Twitter URL for Hal like so: [mytwitter person="hal"]. Shortcodes can also accept multiple attributes from the array set in your shortcode function. c08.indd 174 12/6/12 1:19 AM WordPress Integration ❘ 175Creating a Widget Widgets are a common feature included in many WordPress plugins. By creating a widget with your plugin, you can easily give users a way to add your plugin information to their sidebar or other widgetized areas.To understand how widgets work, it’s helpful to view an overview of the WP_Widget class in WordPress. The widget class features built-in functions for building a widget, each with a specifi c purpose, as shown in the following code: <?php class My_Widget extends WP_Widget { function My_Widget() { // process the widget } function form($instance) { // widget form in admin dashboard } function update($new_instance, $old_instance) { // save widget options } function widget($args, $instance) { // display the widget } } ?> As an example, you’ll create a basic bio widget. This widget will allow you to set a person’s name and custom bio to display in a widgetized sidebar in WordPress. The fi rst step in creating your own widget is to use the appropriate hook to initialize your widget. This hook is called widgets_init and is triggered right after the default WordPress widgets have been registered: add_action( 'widgets_init', 'prowp_register_widgets' ); function prowp_register_widgets() { register_widget( 'prowp_widget' );}Calling the Action hook widgets_init executes the function prowp_register_widgets(), as shown in the preceding code. Here you register your widget called pro_widget. You could also register multiple widgets in this function if needed. The revamped Widget API released with WordPress 2.8 makes creating a widget much easier than before. To begin, you have to extend the preexisting WP_Widget class by creating a new class with a unique name, as shown here: class prowp_widget extends WP_Widget { c08.indd 175 12/6/12 1:19 AM 176 ❘ CHAPTER 8 PLUGIN DEVELOPMENTNext, you’ll add your fi rst function, which should be the same name as your unique class name. This is referred to as the constructor: function prowp_widget() {$widget_ops = array( 'classname' => 'prowp_widget_class', 'description' => 'Example widget that displays a user\'s bio.' ); $this->WP_Widget( 'prowp_widget', 'Bio Widget', $widget_ops );}In your prowp_widget() function, you defi ne your classname for your widget. The classname is the CSS class that will be added to the HTML tag wrapping the widget when it’s displayed. Depending on the theme the CSS class may be in a <div>, <aside>, <li>, or other HTML tag. You also set the description for your widget. This is displayed on the widget dashboard below the widget name. These options are then passed to WP_Widget. You also pass the CSS ID name (prowp_widget_ class) and the widget name (Bio Widget). Next you need to create the function to build your widget settings form. Widget settings are located on the widget admin page upon expanding any widget listed on a sidebar. The widget class makes this process very easy, as shown in the following code: function form( $instance ) { $defaults = array( 'title' => 'My Bio', 'name' => 'Michael Myers', 'bio' => '' ); $instance = wp_parse_args( (array) $instance, $defaults ); $title = $instance['title']; $name = $instance['name']; $bio = $instance['bio']; ?> Title: <input class="widefat" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" /> Name: <input class="widefat" name="<?php echo $this->get_field_name( 'name' ); ?>" type="text" value="<?php echo esc_attr( $name ); ?>" /> Bio: <textarea class="widefat" name="<?php echo $this->get_field_name( 'bio' ); ?>" > <?php echo esc_textarea( $bio ); ?></textarea> <?php } The fi rst thing you do is defi ne your default widget values. If the user doesn’t fi ll in the settings, you can default these values to whatever you like. In this case, you’re setting the default title to My Bio and default name to Michael Myers. Next, you pull in the instance values, which are your widget settings. If the widget was just added to a sidebar, there are no settings saved so these values will be empty. Finally, you display the three form fi elds for your widget settings: title, name, and bio. The c08.indd 176 12/6/12 1:19 AM WordPress Integration ❘ 177 fi rst two values are using text input boxes and the bio value is using a text area box. Notice that you don’t need <form> tags or a submit button; the widget class will handle this for you. Remember to use the appropriate escaping functions when displaying your data, in this case esc_attr() for the two text fi elds and esc_textarea() for the text area fi eld. Next, you need to save your widget settings using the update() widget class function: function update( $new_instance, $old_instance ) {$instance = $old_instance; $instance['title'] = sanitize_text_field( $new_instance['title'] ); $instance['name'] = sanitize_text_field( $new_instance['name'] ); $instance['bio'] = sanitize_text_field( $new_instance['bio'] ); return $instance;} This function is pretty straightforward. You’ll notice you don’t need to save the settings yourself, the widget class does it for you. You pass in the $new_instance values for each of your setting fi elds. You’re also using sanitize_text_field() to strip out any HTML that might be entered. If you want to accept HTML values, you’d use wp_kses() instead, which was covered earlier in the, “Data Validation and Sanitization,” section of this chapter.The fi nal function in your prowp_widget class handles displaying your widget: function widget( $args, $instance ) { extract( $args ); echo $before_widget;$title = apply_filters( 'widget_title', $instance['title'] ); $name = ( empty( $instance['name'] ) ) ? ' ' : $instance['name']; $bio = ( empty( $instance['bio'] ) ) ? ' ' : $instance['bio']; if ( !empty( $title ) ) { echo $before_title . esc_html( $title ) . $after_title; }; echo 'Name: ' . esc_html( $name ) . ''; echo 'Bio: ' . esc_html( $bio ) . ''; echo $after_widget;}The fi rst thing you do is extract the $args parameter. This variable stores some global theme values such as $before_widget and $after_widget. These variables can be used by theme developers to customize what code will wrap your widget — for example, a custom <div> tag. After extracting the $args parameter, you display the $before_widget variable. The $before_title and $after_ title are also set in this variable. This is useful for passing custom HTML tags to wrap the widget title in. Next, you display your widget values. The title is displayed fi rst and wrapped by $before_title and $after_title. Next, you echo out the name and bio values. Remember to escape the widget values for security reasons. Finally, you display the $after_widget value. c08.indd 177 12/6/12 1:19 AM 178 ❘ CHAPTER 8 PLUGIN DEVELOPMENTThat’s it! You’ve just created a custom widget for your plugin using the widget class in WordPress. Remember that by using the new widget class, you can add multiple copies of the same widget to the sidebar or additional sidebars. Listing 8-4 shows the completed widget code.LISTING 8-4: Custom Widget (prowp2-custom-widget.zip)<?php// use widgets_init Action hook to execute custom function add_action( 'widgets_init', 'prowp_register_widgets' );//register our widget function prowp_register_widgets() { register_widget( 'prowp_widget' );}//prowpwidget class class prowp_widget extends WP_Widget {//process our new widget function prowp_widget() {$widget_ops = array( 'classname' => 'prowp_widget_class', 'description' => 'Example widget that displays a user\'s bio.' ); $this->WP_Widget( 'prowp_widget', 'Bio Widget', $widget_ops );}//build our widget settings form function form( $instance ) { $defaults = array( 'title' => 'My Bio', 'name' => 'Michael Myers', 'bio' => '' ); $instance = wp_parse_args( (array) $instance, $defaults ); $title = $instance['title']; $name = $instance['name']; $bio = $instance['bio']; ?> Title: <input class="widefat" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" /> Name: <input class="widefat" name="<?php echo $this->get_field_name( 'name' ); c08.indd 178 12/6/12 1:19 AM WordPress Integration ❘ 179?>" type="text" value="<?php echo esc_attr( $name ); ?>" /> Bio: <textarea class="widefat" name="<?php echo $this->get_field_name( 'bio' ); ?>" ><?php echo esc_textarea( $bio ); ?></textarea> <?php }//save our widget settings function update( $new_instance, $old_instance ) {$instance = $old_instance; $instance['title'] = sanitize_text_field( $new_instance['title'] ); $instance['name'] = sanitize_text_field( $new_instance['name'] ); $instance['bio'] = sanitize_text_field( $new_instance['bio'] ); return $instance;}//display our widget function widget( $args, $instance ) { extract( $args ); echo $before_widget;$title = apply_filters( 'widget_title', $instance['title'] ); $name = ( empty( $instance['name'] ) ) ? ' ' : $instance['name']; $bio = ( empty( $instance['bio'] ) ) ? ' ' : $instance['bio']; if ( !empty( $title ) ) { echo $before_title . esc_html( $title ) . $after_title; }; echo 'Name: ' . esc_html( $name ) . ''; echo 'Bio: ' . esc_html( $bio ) . ''; echo $after_widget;} } ?> Creating a Dashboard Widget WordPress 2.7 introduced Dashboard Widgets, which are the widgets displayed on the main Dashboard of your WordPress installation. Along with these new widgets came the Dashboard Widgets API, which allows you to create any custom Dashboard Widget that you would like. c08.indd 179 12/6/12 1:19 AM 180 ❘ CHAPTER 8 PLUGIN DEVELOPMENTTo create a custom Dashboard Widget, you’ll use the wp_add_dashboard_widget() function, as shown here: <?php add_action( 'wp_dashboard_setup', 'prowp_add_dashboard_widget' );// call function to create our dashboard widget function prowp_add_dashboard_widget() { wp_add_dashboard_widget( 'prowp_dashboard_widget', 'Pro WP Dashboard Widget', 'prowp_create_dashboard_widget' );}// function to display our dashboard widget content function prowp_create_dashboard_widget() { echo 'Hello World! This is my Dashboard Widget';} ?>First you call the wp_dashboard_setup Action hook to execute the function to build your custom Dashboard Widget. This hook is triggered after all of the default Dashboard Widgets have been built. Next you execute the wp_add_dashboard_widget() function to create your Dashboard Widget. The fi rst parameter is the widget ID slug. This is used for the CSS classname and the key in the array of widgets. The next parameter is the display name for your widget. The fi nal parameter you send is your custom function name to display your widget contents. An optional fourth parameter can be sent for a control callback function. This function would be used to process any form elements that might exist in your Dashboard Widget.After executing the wp_add_dashboard_widget() function your custom function is called to display your widget contents. In this example, you display a simple string. The result is a custom Dashboard Widget, as shown in Figure 8-6.Creating Custom Tables FIGURE 8-6: Example dashboard widget WordPress contains a variety of tables in which to store your plugin data. However, you might fi nd that your plugin needs a custom table or two to store plugin data. This can be useful for more complex plugins such as an e-commerce plugin, which stores order history, product and inventory data, and other data that is accessed using database SQL semantics rather than the simple key and value pairing of the options table. The fi rst step in creating a custom database table is to create an installation function. You will execute this function when the plugin is activated to create your new table. c08.indd 180 12/6/12 1:19 AM WordPress Integration ❘ 181<?php register_activation_hook( __FILE__, 'prowp_install' ); function prowp_install() {} ?> Now that you have an installation function, you need to defi ne your custom table name. Remember that the table prefi x can be custom defi ned by the user in wp-config.php, and as discussed in Chapter 10, WordPress Multisite can insert additional prefi x data into the table names so you need to incorporate these table prefi xes for your custom table name. To get the table prefi x, you use the global $wpdb->prefix value like so: global $wpdb;//define the custom table name $table_name = $wpdb->prefix .'prowp_data';This code stores your table named wp_prowp_data in the $table_name variable, assuming your WordPress table prefi x is set towp_ . Now it’s time to build your SQL query for creating your new table. You’ll create your query in a variable called $sql before executing it. You also need to include the upgrade.php fi le prior to executing your query like so: $sql = "CREATE TABLE " .$table_name ." ( id mediumint(9) NOT NULL AUTO_INCREMENT, time bigint(11) DEFAULT '0' NOT NULL, name tinytext NOT NULL, text text NOT NULL, url VARCHAR(55) NOT NULL, UNIQUE KEY id (id) );"; require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );//execute the query creating our table dbDelta( $sql );After this executes, your new table has been created in the database. The dbDelta() function will verify fi rst that the table you are creating doesn’t exist, so you don’t have to worry about checking if a table exists before creating it. It’s also a good idea to save the version number for your database table structure. This can help down the road if you upgrade your plugin and need to change the table structure. You can check what table version the users have installed for your plugin and determine if they need to upgrade: $prowp_db_version = '1.0'; add_option( 'prowp_db_version', $prowp_db_version ); Look at the full function in action: register_activation_hook( __FILE__, 'prowp_install' ); function prowp_install() { c08.indd 181 12/6/12 1:19 AM 182 ❘ CHAPTER 8 PLUGIN DEVELOPMENT global $wpdb;//define the custom table name $table_name = $wpdb->prefix .'prowp_data';//build the query to create our new table $sql = "CREATE TABLE " .$table_name ." ( id mediumint(9) NOT NULL AUTO_INCREMENT, time bigint(11) DEFAULT '0' NOT NULL, name tinytext NOT NULL, text text NOT NULL, url VARCHAR(55) NOT NULL, UNIQUE KEY id (id) );"; require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );//execute the query to create our table dbDelta( $sql );//set the table structure version $prowp_db_version = '1.0';//save the table structure version number add_option( 'prowp_db_version', $prowp_db_version );} If you want to upgrade your table structure for a new version of your plugin, you can just compare the table structure version numbers: $installed_ver = get_option( 'gmp_db_version' ); if( $installed_ver != $prowp_db_version ) {//update database table here//update table version update_option( 'gmp_db_version', $prowp_db_version );} Before creating a custom table for your plugin, you should consider whether this is the best method. It’s generally a good idea to avoid creating custom tables unless there is no alternative. Remember that you can easily store options in WordPress using the options API. You can also utilize the wp_*meta tables for storing extended data about posts, pages, comments, and users. Custom post types are also a great place to store data. To work with a custom table once you’ve created it, you’ll need to use the WordPress database class, as shown in Chapter 6.Uninstalling Your Plugin A nice feature to include with your plugin is an uninstall feature. WordPress features two ways to register the uninstaller for your plugin: the uninstall.php method and the uninstall hook. Both methods are executed when a deactivated plugin is deleted in the WordPress admin dashboard. c08.indd 182 12/6/12 1:19 AM WordPress Integration ❘ 183The fi rst method you’ll look at is the uninstall.php uninstaller method. This is the preferred method for uninstalling a plugin. The fi rst step to using this method is to create an uninstall.php fi le. This fi le must exist in the root directory of your plugin, and if it does, it will execute in preference to the uninstall hook. <?php // If uninstall/delete not called from WordPress then exit if( !defined( 'ABSPATH' ) && !defined( 'WP_UNINSTALL_PLUGIN' ) ) exit();// Delete option from options table delete_option( 'prowp_options_arr' );// Delete any other options, custom tables/data, files ?>The fi rst thing youruninstall.php fi le should check is that ABSPATH and WP_UNINSTALL_PLUGIN constants have been defi ned, meaning they were actually called from WordPress. This is a security measure to ensure this fi le is not executed except during the uninstall process of your plugin. The next step is to remove any options and custom tables your plugin created. In a perfect uninstall scenario there would be no trace of your plugin left over in the database once it had been uninstalled. The preceding example uses delete_option() to delete the option array. Remember that once this function runs, all custom plugin data saved will be destroyed. The second method for uninstalling a plugin is to use the Uninstall hook. When a plugin is deleted, and uninstall.php does not exist but the Uninstall hook does exist, the plugin will be run one last time to execute the Uninstall hook. After the hook has been called, your plugin will be deleted. Here’s the Uninstall hook in action: <?php register_uninstall_hook( __FILE__, 'prowp_uninstall_hook' ); function prowp_uninstall_hook() { delete_option( 'prowp_options_arr' );//remove any additional options and custom tables} ?> First you call your custom uninstall function to properly uninstall your plugin options. If you do include uninstall functionality in your plugin, such as removing custom tables and options, make sure to warn the users that all plugin data will be deleted if they delete the plugin.The difference between this method and the register_deactivation_hook is that the register_uninstall_hook is executed when a deactivated plugin is deleted. The register _deactivation_hook is executed when the plugin is deactivated, which means the user may want to activate the plugin again eventually. You wouldn’t want to delete all of the plugin settings if the user is planning on using your plugin again. c08.indd 183 12/6/12 1:19 AM 184 ❘ CHAPTER 8 PLUGIN DEVELOPMENTCREATING A PLUGIN EXAMPLENow that you’ve seen the many different options WordPress provides for use in your plugins, you can put that knowledge to work! In this example, you will utilize many of the features covered in this chapter. At the end of this section, the entire plugin source code will be available. The example plugin you are going to build is a basic Halloween Store. The goal of this plugin is to create an easy way to add products to WordPress and display the products in your Halloween Store. This plugin will include the following features: ➤ Settings page using the Settings API ➤ Widget for displaying newest products using the Widget class ➤ Post meta box for adding product metadata ➤ Shortcode support to easily display product data in a post ➤ Internationalization support using translation functions The fi rst step in creating your plugin is to create your plugin fi les. For this plugin, you’ll have two fi les: halloween-store.php and uninstall.php. Because your plugin contains two fi les, you’ll need to save these fi les in a separate folder for your plugin named halloween-store. Next, you need to set up your plugin header and license.To start, you’ll be working in halloween-store.php. First you want to defi ne your plugin header, as shown here: <?php /* Plugin Name: Halloween Store Plugin URI: http://webdevstudios.com/support/wordpress-plugins/ Description: Create a Halloween Store to display product information Version: 1.0 Author: Brad Williams Author URI: http://webdevstudios.com License: GPLv2 *//* Copyright 2013 Brad Williams (email : brad@webdevstudios.com)This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ c08.indd 184 12/6/12 1:19 AM Creating a Plugin Example ❘ 185As you can see, you created the appropriate plugin header for your new plugin. Because you will be releasing this plugin, you’ll want to include the GPL software license below your plugin header.Next you are going to call the register_activation_hook() function to set up your default plugin settings. Remember that this function is triggered when a user activates your plugin in WordPress. // Call function when plugin is activated register_activation_hook( __FILE__, 'halloween_store_install' ); function halloween_store_install() {//setup default option values $hween_options_arr = array( 'currency_sign' => '$' );//save our default option values update_option( 'halloween_options', $hween_options_arr );}As you can see, this plugin will store an array of settings in a single option called halloween_ options. When the plugin is activated, you set the default currency_sign value to $.Next, you call the init hook to register the custom post type for Products. This is how you will add and manage your Halloween Store products. // Action hook to initialize the plugin add_action( 'init', 'halloween_store_init' );//Initialize the Halloween Store function halloween_store_init() {//register the products custom post type $labels = array( 'name' => __( 'Products', 'halloween-plugin' ), 'singular_name' => __( 'Product', 'halloween-plugin' ), 'add_new' => __( 'Add New', 'halloween-plugin' ), 'add_new_item' => __( 'Add New Product', 'halloween-plugin' ), 'edit_item' => __( 'Edit Product', 'halloween-plugin' ), 'new_item' => __( 'New Product', 'halloween-plugin' ), 'all_items' => __( 'All Products', 'halloween-plugin' ), 'view_item' => __( 'View Product', 'halloween-plugin' ), 'search_items' => __( 'Search Products', 'halloween-plugin' ), 'not_found' => __( 'No products found', 'halloween-plugin' ), 'not_found_in_trash' => __( 'No products found in Trash', 'halloween-plugin' ), 'menu_name' => __( 'Products', 'halloween-plugin' ) );$args = array( 'labels' => $labels, 'public' => true, 'publicly_queryable' => true, 'show_ui' => true, c08.indd 185 12/6/12 1:19 AM 186 ❘ CHAPTER 8 PLUGIN DEVELOPMENT'show_in_menu' => true, 'query_var' => true, 'rewrite' => true, 'capability_type' => 'post', 'has_archive' => true, 'hierarchical' => false, 'menu_position' => null, 'supports' => array( 'title', 'editor', 'thumbnail', 'excerpt' ) ); register_post_type( 'halloween-products', $args );}Notice that you are wrapping each translatable term in the __() translation function. This allows users to translate the terms into any language they want. You’ll see these translation functions used throughout this plugin example. Now you’ll create the Halloween Store settings page. The fi rst step is to add a Settings submenu item for your settings page using the add_options_page() function: // Action hook to add the post products menu item add_action( 'admin_menu', 'halloween_store_menu' );//create the Halloween Masks sub-menu function halloween_store_menu() { add_options_page( __( 'Halloween Store Settings Page', 'halloween-plugin' ), __( 'Halloween Store Settings', 'halloween-plugin' ), 'manage_options', 'halloween-store-settings', 'halloween_store_settings_page' );} As you can see, this function is used to create your submenu item. Your Halloween Store Settings submenu item will be located at the bottom of the Settings menu in your Dashboard. You also set this menu item to be viewable by an administrator only. Now you need to build the actual settings page. As shown in the preceding code, the Halloween Store Settings page triggers your custom halloween_store_settings_page() function. //build the plugin settings page function halloween_store_settings_page() {//load the plugin options array $hween_options_arr = get_option( 'halloween_options' );//set the option array values to variables $hs_inventory = ( ! empty( $hween_options_arr['show_inventory'] ) ) ? $hween_options_arr['show_inventory'] : ''; $hs_currency_sign = $hween_options_arr['currency_sign']; ?> <div class="wrap"> <h2><?php _e( 'Halloween Store Options', 'halloween-plugin' ) ?></h2><form method="post" action="options.php"> c08.indd 186 12/6/12 1:19 AM Creating a Plugin Example ❘ 187<?php settings_fields( 'halloween-settings-group' ); ?> <table class="form-table"> <tr valign="top"> <th scope="row"><?php _e( 'Show Product Inventory', 'halloween-plugin' ) ?></th> <td><input type="checkbox" name="halloween_options[show_inventory]" <?php echo checked( $hs_inventory, 'on' ); ?> /></td> </tr><tr valign="top"> <th scope="row"><?php _e( 'Currency Sign', 'halloween-plugin' ) ?></th> <td><input type="text" name="halloween_options[currency_sign]" value="<?php echo esc_attr( $hs_currency_sign ); ?>" size="1" maxlength="1" /></td> </tr> </table> <input type="submit" class="button-primary" value="<?php _e( 'Save Changes', 'halloween-plugin' ); ?>" /> </form> </div> <?php } Your Halloween Store plugin has two options: whether to show product inventory and the currency sign to use. First you load your plugin options array value. Next, set the two option values to variables. You use a PHP ternary operator to set the default value for Inventory. You also load in the current currency value into a variable for display. Next, you display your settings page form with both option form fi elds listed. Notice that you are using the settings_fields() function to link your settings form to your registered setting that you will defi ne in the code that follows. This is the proper way to save your setting options in an array using the Settings API. When the form is submitted, WordPress will use the Settings API to sanitize the form values and save them in the database. To make this work, you need to register your settings fi eld and sanitization functions: // Action hook to register the plugin option settings add_action( 'admin_init', 'halloween_store_register_settings' ); function halloween_store_register_settings() {//register the array of settings register_setting( 'halloween-settings-group', 'halloween_options', 'halloween_sanitize_options' );} function halloween_sanitize_options( $options ) {$options['show_inventory'] = ( ! empty( $options['show_inventory'] ) ) ? sanitize_text_field( $options['show_inventory'] ) : ''; $options['currency_sign'] = ( ! empty( $options['currency_sign'] ) ) ? c08.indd 187 12/6/12 1:19 AM 188 ❘ CHAPTER 8 PLUGIN DEVELOPMENT sanitize_text_field( $options['currency_sign'] ) : ''; return $options;}Using the register_setting() function, you register the settings group, halloween-settings- group, and the option name, halloween-options, to be used in your settings form. The hallow- een_sanitize_options() function is used to sanitize the user input for each setting prior to saving in WordPress. This is a very important security step to verify that the data being submitted is properly sanitized before being saved in the database. Now that your plugin settings are saved, it’s time to register the Meta Box for saving Product metadata: //Action hook to register the Products meta box add_action( 'add_meta_boxes', 'halloween_store_register_meta_box' ); function halloween_store_register_meta_box() {// create our custom meta box add_meta_box( 'halloween-product-meta', __( 'Product Information','halloween-plugin' ), 'halloween_meta_box', 'halloween-products', 'side', 'default' );}Using the add_meta_boxes action hook, you’ll call your custom function for registering the Products meta box. The add_meta_box() function is used to do the actual registering. Now that the meta box is registered, you need to build the meta box form: //build product meta box function halloween_meta_box( $post ) {// retrieve our custom meta box values $hween_sku = get_post_meta( $post->ID, '_halloween_product_sku', true ); $hween_price = get_post_meta( $post->ID, '_halloween_product_price', true ); $hween_weight = get_post_meta( $post->ID, '_halloween_product_weight', true ); $hween_color = get_post_meta( $post->ID, '_halloween_product_color', true ); $hween_inventory = get_post_meta( $post->ID, '_halloween_product_inventory', true );//nonce field for security wp_nonce_field( 'meta-box-save', 'halloween-plugin' );// display meta box form echo '<table>'; echo '<tr>'; echo '<td>' .__('Sku', 'halloween-plugin').':</td> <td><input type="text" name="halloween_product_sku" value="'.esc_attr( $hween_sku ).'" size="10"></td>'; echo '</tr><tr>'; echo '<td>' .__('Price', 'halloween-plugin').':</td> <td><input type="text" name="halloween_product_price" value="'.esc_attr( $hween_price ).'" size="5"></td>'; echo '</tr><tr>'; c08.indd 188 12/6/12 1:19 AM Creating a Plugin Example ❘ 189 echo '<td>' .__('Weight', 'halloween-plugin').':</td> <td><input type="text" name="halloween_product_weight" value="'.esc_attr( $hween_weight ).'" size="5"></td>'; echo '</tr><tr>'; echo '<td>' .__('Color', 'halloween-plugin').':</td> <td><input type="text" name="halloween_product_color" value="'.esc_attr( $hween_color ).'" size="5"></td>'; echo '</tr><tr>'; echo '<td>Inventory:</td> <td><select name="halloween_product_inventory" id="halloween_product_inventory"> <option value="In Stock"' .selected( $hween_inventory, 'In Stock', false ). '>' .__( 'In Stock', 'halloween-plugin' ). '</option> <option value="Backordered"' .selected( $hween_inventory, 'Backordered', false ). '>' .__( 'Backordered', 'halloween-plugin' ). '</option> <option value="Out of Stock"' .selected( $hween_inventory, 'Out of Stock', false ). '>' .__( 'Out of Stock', 'halloween-plugin' ). '</option> <option value="Discontinued"' .selected( $hween_inventory, 'Discontinued', false ). '>' .__( 'Discontinued', 'halloween-plugin' ). '</option> </select></td>'; echo '</tr>';//display the meta box shortcode legend section echo '<tr><td colspan="2"><hr></td></tr>'; echo '<tr><td colspan="2">' .__( 'Shortcode Legend', 'halloween-plugin' ).'</td></tr>'; echo '<tr><td>' .__( 'Sku', 'halloween-plugin' ) .': </td><td>[hs show=sku]</td></tr>'; echo '<tr><td>' .__( 'Price', 'halloween-plugin' ).': </td><td>[hs show=price]</td></tr>'; echo '<tr><td>' .__( 'Weight', 'halloween-plugin' ).': </td><td>[hs show=weight]</td></tr>'; echo '<tr><td>' .__( 'Color', 'halloween-plugin' ).': </td><td>[hs show=color]</td></tr>'; echo '<tr><td>' .__( 'Inventory', 'halloween-plugin' ).': </td><td>[hs show=inventory]</td></tr>'; echo '</table>'; } Your Halloween Store plugin saves fi ve different product values on every product: SKU, price, weight, color, and inventory. As you can see, the fi rst step is to load these five custom fi eld values. Next, you display the meta box form and fi ll in the current values if any exist. Below the meta box form, you display a simple shortcode legend to show the user what shortcode options are available for displaying the product metadata. Once completed, your custom meta box will look like Figure 8-7.FIGURE 8-7: Post product meta box c08.indd 189 12/6/12 1:19 AM 190 ❘ CHAPTER 8 PLUGIN DEVELOPMENTNow that you’ve created your custom meta box, you need to save the data entered in the form, as shown in the following code: // Action hook to save the meta box data when the post is saved add_action( 'save_post','halloween_store_save_meta_box' );//save meta box data function halloween_store_save_meta_box( $post_id ) {//verify the post type is for Halloween Products and metadata has been posted if ( get_post_type( $post_id ) == 'halloween-products' && isset( $_POST['halloween_product_sku'] ) ) {//if autosave skip saving data if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;//check nonce for security check_admin_referer( 'meta-box-save', 'halloween-plugin' );// save the meta box data as post metadata update_post_meta( $post_id, '_halloween_product_sku', sanitize_text_field( $_POST['halloween_product_sku'] ) ); update_post_meta( $post_id, '_halloween_product_price', sanitize_text_field( $_POST['halloween_product_price'] ) ); update_post_meta( $post_id, '_halloween_product_weight', sanitize_text_field( $_POST['halloween_product_weight'] ) ); update_post_meta( $post_id, '_halloween_product_color', sanitize_text_field( $_POST['halloween_product_color'] ) ); update_post_meta( $post_id, '_halloween_product_inventory', sanitize_text_field( $_POST['halloween_product_inventory'] ) );}}First you need to verify that the post being saved is a halloween-products custom post type entry. You also verify the $_POST['halloween_product_sku'] value is set before proceeding. The only required fi eld is the product SKU, so if this fi eld is blank, the product data will not be saved. After you have verifi ed that a SKU exists, you need to verify that the post is not an autosave. You also need to verify the nonce for security using check_admin_referer(). After all checks have passed, you save your custom product fi elds as product metadata for the product you are creating or updating. Next, you’re going to set up the plugin shortcode. This will allow you to easily display any or all Product metadata in the Product content.// Action hook to create the products shortcode add_shortcode( 'hs', 'halloween_store_shortcode' );//create shortcode function halloween_store_shortcode( $atts, $content = null ) { c08.indd 190 12/6/12 1:20 AM Creating a Plugin Example ❘ 191 global $post; extract( shortcode_atts( array( "show" => '' ), $atts ) );//load options array $hween_options_arr = get_option( 'halloween_options' ); if ( $show == 'sku') {$hs_show = get_post_meta( $post->ID, '_halloween_product_sku', true );}elseif ( $show == 'price' ) {$hs_show = $hween_options_arr['currency_sign']. get_post_meta( $post->ID, '_halloween_product_price', true );}elseif ( $show == 'weight' ) {$hs_show = get_post_meta( $post->ID, '_halloween_product_weight', true );}elseif ( $show == 'color' ) {$hs_show = get_post_meta( $post->ID, '_halloween_product_color', true );}elseif ( $show == 'inventory' ) {$hs_show = get_post_meta( $post->ID, '_halloween_product_inventory', true );}//return the shortcode value to display return $hs_show;}The fi rst thing you do is initialize the global variable $post. This will bring in the $post->ID value for the post in which you are using the shortcode. Next, you extract the shortcode attributes that you’ve defi ned, in this case show. Finally, you check what attribute value is being sent to the shortcode to determine what value to show. Using the shortcode like [hs show=price] would display the price of the product. If the price metadata is being displayed, you’ll need to retrieve the currency sign option value that was set by the user. Next up, you are going to create your products widget:// Action hook to create plugin widget add_action( 'widgets_init', 'halloween_store_register_widgets' );//register the widget c08.indd 191 12/6/12 1:20 AM 192 ❘ CHAPTER 8 PLUGIN DEVELOPMENT function halloween_store_register_widgets() { register_widget( 'hs_widget' );}//hs_widget class class hs_widget extends WP_Widget {First you have to register your widget as hs_widget using the register_widget() function. Next, you extend the Widget class as hs_widget. Now you need to create the four widget functions needed to build your widget: //process our new widget function hs_widget() {$widget_ops = array( 'classname' => 'hs-widget-class', 'description' => __( 'Display Halloween Products', 'halloween-plugin' ) ); $this->WP_Widget( 'hs_widget', __( 'Products Widget', 'halloween-plugin'), $widget_ops );}The fi rst function you create is the hs_widget() function, also known as the constructor. Here, you set the widget title, description, and class name for your custom widget: //build our widget settings form function form( $instance ) {$defaults = array( 'title' => __( 'Products', 'halloween-plugin' ), 'number_products' => '3' );$instance = wp_parse_args( (array) $instance, $defaults ); $title = $instance['title']; $number_products = $instance['number_products']; ?> <?php _e('Title', 'halloween-plugin') ?>: <input class="widefat" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" /> <?php _e( 'Number of Products', 'halloween-plugin' ) ?>: <input name=" <?php echo $this->get_field_name( 'number_products' ); ?>" type="text" value="<?php echo esc_attr( $number_products ); ?>" size="2" maxlength="2" /> <?php }The second function you defi ne is the form() function. This builds the form for saving your widget settings. You are saving two settings in your widget: the widget title and the number of products to display. First, you defi ne the setting defaults if no settings have been saved. Next, you load in the c08.indd 192 12/6/12 1:20 AM Creating a Plugin Example ❘ 193 saved values for your two settings. Finally, you display both setting form fi elds with the setting values if they exist. //save our widget settings function update( $new_instance, $old_instance ) {$instance = $old_instance; $instance['title'] = sanitize_text_field( $new_instance['title'] ); $instance['number_products'] = absint( $new_instance['number_products'] ); return $instance;}The next function you create is the update() function. This function saves your widget settings. Notice how you utilize the sanitize_text_field()function to sanitize your widget title. You also use the PHP absint() function to verify that the number of products value is a non-negative integer. //display our widget function widget( $args, $instance ) { global $post; extract( $args ); echo $before_widget; $title = apply_filters( 'widget_title', $instance['title'] ); $number_products = $instance['number_products']; if ( ! empty( $title ) ) { echo $before_title . esc_html( $title ) . $after_title; };//custom query to retrieve products $args = array( 'post_type' => 'halloween-products', 'posts_per_page' => absint( $number_products ) );$dispProducts = new WP_Query(); $dispProducts->query( $args ); while ( $dispProducts->have_posts() ) : $dispProducts->the_post();//load options array $hween_options_arr = get_option( 'halloween_options' );//load custom meta values $hs_price = get_post_meta( $post->ID, '_halloween_product_price', true ); $hs_inventory = get_post_meta( $post->ID, '_halloween_product_inventory', true ); ?> <a href="<?php the_permalink(); ?>" rel="bookmark" c08.indd 193 12/6/12 1:20 AM 194 ❘ CHAPTER 8 PLUGIN DEVELOPMENT title="<?php the_title_attribute(); ?> Product Information"> <?php the_title(); ?> </a> <?php echo '' .__( 'Price', 'halloween-plugin' ). ': ' .$hween_options_arr['currency_sign'] .$hs_price .'';//check if Show Inventory option is enabled if ( $hween_options_arr['show_inventory'] ) {//display the inventory metadata for this product echo '' .__( 'Stock', 'halloween-plugin' ). ': ' .$hs_inventory .'';} echo '<hr>'; endwhile; wp_reset_postdata(); echo $after_widget;} }The fi nal function defi ned is the widget() function. This function displays your widget on the public side of your website. First you initialize the global $post variable and extract the $args for the widget. Then you display the $before_widget variable. This variable can be set by theme and plugin developers to display specifi ed content before and after the plugin. Next, you retrieve your two setting values. If the $title value is not empty, you use it, but if it is, you’ll use the default title you defi ned earlier.To display the products in your widget, you are creating a custom Loop using WP_Query, as discussed in Chapter 5. Remember that because this is not your main Loop, you’ll want to use WP_Query to create your custom Loop instead of query_posts(). To defi ne your custom Loop, you pass in two parameters: one for the post type and one for number of products to display. The fi rst value (post_type=halloween-products) tells your custom Loop to only return Halloween product entries. The second value, posts_per_page, determines how many products to display. This number is pulled from the widget options value set by the user. Next, you load your option values and the custom metadata values you will be displaying in your widget. Finally, you display your product values in the widget. If the option Show Inventory is enabled, the inventory value will be displayed. After successfully creating the Products widget, it should look like Figure 8-8.The fi nal step for your Halloween Store plugin is to create your uninstall.php fi le: FIGURE 8-8: Products widget c08.indd 194 12/6/12 1:20 AM Creating a Plugin Example ❘ 195<?php //if uninstall/delete not called from WordPress exit if( ! defined( 'ABSPATH' ) && ! defined( 'WP_UNINSTALL_PLUGIN' ) ) exit ();// Delete options array from options table delete_option( 'halloween_options' ); ?>The fi rst thing you check is that ABSPATH and WP_UNINSTALL_PLUGIN constants exist. This means they were called from WordPress and add a layer of security on the uninstaller. After you have verifi ed that the request is valid, you delete your single option value from the database. You could also defi ne other uninstall functionality here, if needed, such as removing every product metadata value you saved in the database. That’s it! You just successfully built an entire plugin that includes many of the features covered in this chapter. This is a fairly basic plugin but should give you the examples and tools needed to expand upon. Listing 8-5 shows the plugin source code in its entirety. To access this code online, visit https://github.com/williamsba/HalloweenStore.LISTING 8-5: Complete Plugin Source Code (halloween-store.zip)<?php /* Plugin Name: Halloween Store Plugin URI: http://webdevstudios.com/support/wordpress-plugins/ Description: Create a Halloween Store to display product information Version: 1.0 Author: Brad Williams Author URI: http://webdevstudios.com License: GPLv2 *//* Copyright 2013 Brad Williams (email : brad@webdevstudios.com)This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */// Call function when plugin is activated continues c08.indd 195 12/6/12 1:20 AM 196 ❘ CHAPTER 8 PLUGIN DEVELOPMENTLISTING 8-5 (continued) register_activation_hook( __FILE__, 'halloween_store_install' ); function halloween_store_install() {//setup default option values $hween_options_arr = array( 'currency_sign' => '$' );//save our default option values update_option( 'halloween_options', $hween_options_arr );}// Action hook to initialize the plugin add_action( 'init', 'halloween_store_init' );//Initialize the Halloween Store function halloween_store_init() {//register the products custom post type $labels = array( 'name' => __( 'Products', 'halloween-plugin' ), 'singular_name' => __( 'Product', 'halloween-plugin' ), 'add_new' => __( 'Add New', 'halloween-plugin' ), 'add_new_item' => __( 'Add New Product', 'halloween-plugin' ), 'edit_item' => __( 'Edit Product', 'halloween-plugin' ), 'new_item' => __( 'New Product', 'halloween-plugin' ), 'all_items' => __( 'All Products', 'halloween-plugin' ), 'view_item' => __( 'View Product', 'halloween-plugin' ), 'search_items' => __( 'Search Products', 'halloween-plugin' ), 'not_found' => __( 'No products found', 'halloween-plugin' ), 'not_found_in_trash' => __( 'No products found in Trash', 'halloween- plugin' ), 'menu_name' => __( 'Products', 'halloween-plugin' ) );$args = array( 'labels' => $labels, 'public' => true, 'publicly_queryable' => true, 'show_ui' => true, 'show_in_menu' => true, 'query_var' => true, 'rewrite' => true, 'capability_type' => 'post', 'has_archive' => true, 'hierarchical' => false, 'menu_position' => null, 'supports' => array( 'title', 'editor', 'thumbnail', 'excerpt' ) c08.indd 196 12/6/12 1:20 AM Creating a Plugin Example ❘ 197); register_post_type( 'halloween-products', $args );}// Action hook to add the post products menu item add_action( 'admin_menu', 'halloween_store_menu' );//create the Halloween Masks sub-menu function halloween_store_menu() { add_options_page( __( 'Halloween Store Settings Page', 'halloween-plugin' ), __( 'Halloween Store Settings', 'halloween-plugin' ), 'manage_options', 'halloween-store-settings', 'halloween_store_settings_page' );}//build the plugin settings page function halloween_store_settings_page() {//load the plugin options array $hween_options_arr = get_option( 'halloween_options' );//set the option array values to variables $hs_inventory = ( ! empty( $hween_options_arr['show_inventory'] ) ) ? $hween_options_arr['show_inventory'] : ''; $hs_currency_sign = $hween_options_arr['currency_sign']; ?> <div class="wrap"> <h2><?php _e( 'Halloween Store Options', 'halloween-plugin' ) ?></h2><form method="post" action="options.php"> <?php settings_fields( 'halloween-settings-group' ); ?> <table class="form-table"> <tr valign="top"> <th scope="row"><?php _e( 'Show Product Inventory', 'halloween-plugin' ) ?></th> <td><input type="checkbox" name="halloween_options[show_inventory]" <?php echo checked( $hs_inventory, 'on' ); ?> /></td> </tr><tr valign="top"> <th scope="row"><?php _e( 'Currency Sign', 'halloween-plugin' ) ?></th> <td><input type="text" name="halloween_options[currency_sign]" value="<?php echo esc_attr( $hs_currency_sign ); ?>" size="1" maxlength="1" /></td> </tr> </table> <input type="submit" class="button-primary" value="<?php _e( 'Save Changes', 'halloween-plugin' ); ?>" /> continues c08.indd 197 12/6/12 1:20 AM 198 ❘ CHAPTER 8 PLUGIN DEVELOPMENTLISTING 8-5 (continued)</form> </div> <?php }// Action hook to register the plugin option settings add_action( 'admin_init', 'halloween_store_register_settings' ); function halloween_store_register_settings() {//register the array of settings register_setting( 'halloween-settings-group', 'halloween_options', 'halloween_sanitize_options' );} function halloween_sanitize_options( $options ) {$options['show_inventory'] = ( ! empty( $options['show_inventory'] ) ) ? sanitize_text_field( $options['show_inventory'] ) : ''; $options['currency_sign'] = ( ! empty( $options['currency_sign'] ) ) ? sanitize_text_field( $options['currency_sign'] ) : ''; return $options;}//Action hook to register the Products meta box add_action( 'add_meta_boxes', 'halloween_store_register_meta_box' ); function halloween_store_register_meta_box() {// create our custom meta box add_meta_box( 'halloween-product-meta', __( 'Product Information','halloween-plugin' ), 'halloween_meta_box', 'halloween-products', 'side', 'default' );}//build product meta box function halloween_meta_box( $post ) {// retrieve our custom meta box values $hween_sku = get_post_meta( $post->ID, '_halloween_product_sku', true ); $hween_price = get_post_meta( $post->ID, '_halloween_product_price', true ); $hween_weight = get_post_meta( $post->ID, '_halloween_product_weight', true ); $hween_color = get_post_meta( $post->ID, '_halloween_product_color', true ); $hween_inventory = get_post_meta( $post->ID, c08.indd 198 12/6/12 1:20 AM Creating a Plugin Example ❘ 199'_halloween_product_inventory', true );//nonce field for security wp_nonce_field( 'meta-box-save', 'halloween-plugin' );// display meta box form echo '<table>'; echo '<tr>'; echo '<td>' .__('Sku', 'halloween-plugin').':</td><td> <input type="text" name="halloween_product_sku" value="'.esc_attr( $hween_sku ).'" size="10"></td>'; echo '</tr><tr>'; echo '<td>' .__('Price', 'halloween-plugin').':</td><td> <input type="text" name="halloween_product_price" value="'.esc_attr( $hween_price ).'" size="5"></td>'; echo '</tr><tr>'; echo '<td>' .__('Weight', 'halloween-plugin').':</td><td> <input type="text" name="halloween_product_weight" value="'.esc_attr( $hween_weight ).'" size="5"></td>'; echo '</tr><tr>'; echo '<td>' .__('Color', 'halloween-plugin').':</td><td> <input type="text" name="halloween_product_color" value="'.esc_attr( $hween_color ).'" size="5"></td>'; echo '</tr><tr>'; echo '<td>Inventory:</td><td> <select name="halloween_product_inventory" id="halloween_product_inventory"> <option value="In Stock"' .selected( $hween_inventory, 'In Stock', false ). '>' .__( 'In Stock', 'halloween-plugin' ) . '</option> <option value="Backordered"' .selected( $hween_inventory, 'Backordered', false ). '>' .__( 'Backordered', 'halloween-plugin' ) . '</option> <option value="Out of Stock"' .selected( $hween_inventory, 'Out of Stock', false ) . '>' .__( 'Out of Stock', 'halloween-plugin' ). '</option> <option value="Discontinued"' .selected( $hween_inventory, 'Discontinued', false ) . '>' .__( 'Discontinued', 'halloween-plugin' ). '</option> </select></td>'; echo '</tr>';//display the meta box shortcode legend section echo '<tr><td colspan="2"><hr></td></tr>'; echo '<tr><td colspan="2">' .__( 'Shortcode Legend', 'halloween-plugin' ).'</td></tr>'; echo '<tr><td>' .__( 'Sku', 'halloween-plugin' ) .':</td><td> [hs show=sku]</td></tr>'; echo '<tr><td>' .__( 'Price', 'halloween-plugin' ).':</td><td> [hs show=price]</td></tr>'; echo '<tr><td>' .__( 'Weight', 'halloween-plugin' ).':</td><td> [hs show=weight]</td></tr>'; echo '<tr><td>' .__( 'Color', 'halloween-plugin' ).':</td><td> continues c08.indd 199 12/6/12 1:20 AM 200 ❘ CHAPTER 8 PLUGIN DEVELOPMENTLISTING 8-5 (continued)[hs show=color]</td></tr>'; echo '<tr><td>' .__( 'Inventory', 'halloween-plugin' ).':</td><td> [hs show=inventory]</td></tr>'; echo '</table>'; }// Action hook to save the meta box data when the post is saved add_action( 'save_post','halloween_store_save_meta_box' );//save meta box data function halloween_store_save_meta_box( $post_id ) {//verify the post type is for Halloween Products and metadata has been posted if ( get_post_type( $post_id ) == 'halloween-products' && isset( $_POST['halloween_product_sku'] ) ) {//if autosave skip saving data if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;//check nonce for security check_admin_referer( 'meta-box-save', 'halloween-plugin' );// save the meta box data as post metadata update_post_meta( $post_id, '_halloween_product_sku', sanitize_text_field( $_POST['halloween_product_sku'] ) ); update_post_meta( $post_id, '_halloween_product_price', sanitize_text_field( $_POST['halloween_product_price'] ) ); update_post_meta( $post_id, '_halloween_product_weight', sanitize_text_field( $_POST['halloween_product_weight'] ) ); update_post_meta( $post_id, '_halloween_product_color', sanitize_text_field( $_POST['halloween_product_color'] ) ); update_post_meta( $post_id, '_halloween_product_inventory', sanitize_text_field( $_POST['halloween_product_inventory'] ) );}}// Action hook to create the products shortcode add_shortcode( 'hs', 'halloween_store_shortcode' );//create shortcode function halloween_store_shortcode( $atts, $content = null ) { global $post; extract( shortcode_atts( array( "show" => '' ), $atts ) );//load options array c08.indd 200 12/6/12 1:20 AM Creating a Plugin Example ❘ 201$hween_options_arr = get_option( 'halloween_options' ); if ( $show == 'sku') {$hs_show = get_post_meta( $post->ID, '_halloween_product_sku', true );}elseif ( $show == 'price' ) {$hs_show = $hween_options_arr['currency_sign']. get_post_meta( $post->ID, '_halloween_product_price', true );}elseif ( $show == 'weight' ) {$hs_show = get_post_meta( $post->ID, '_halloween_product_weight', true );}elseif ( $show == 'color' ) {$hs_show = get_post_meta( $post->ID, '_halloween_product_color', true );}elseif ( $show == 'inventory' ) {$hs_show = get_post_meta( $post->ID, '_halloween_product_inventory', true );}//return the shortcode value to display return $hs_show; }// Action hook to create plugin widget add_action( 'widgets_init', 'halloween_store_register_widgets' );//register the widget function halloween_store_register_widgets() { register_widget( 'hs_widget' );}//hs_widget class class hs_widget extends WP_Widget {//process our new widget function hs_widget() {$widget_ops = array( 'classname' => 'hs-widget-class', 'description' => __( 'Display Halloween Products','halloween- plugin' ) ); $this->WP_Widget( 'hs_widget', __( 'Products Widget','halloween-plugin'), $widget_ops );}//build our widget settings form continues c08.indd 201 12/6/12 1:20 AM 202 ❘ CHAPTER 8 PLUGIN DEVELOPMENTLISTING 8-5 (continued) function form( $instance ) {$defaults = array( 'title' => __( 'Products', 'halloween-plugin' ), 'number_products' => '3' );$instance = wp_parse_args( (array) $instance, $defaults ); $title = $instance['title']; $number_products = $instance['number_products']; ?> <?php _e('Title', 'halloween-plugin') ?>: <input class="widefat" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" /> <?php _e( 'Number of Products', 'halloween-plugin' ) ?>: <input name="<?php echo $this->get_field_name( 'number_products' ); ?>" type="text" value="<?php echo esc_attr( $number_products ); ?>" size="2" maxlength="2" /> <?php }//save our widget settings function update( $new_instance, $old_instance ) {$instance = $old_instance; $instance['title'] = sanitize_text_field( $new_instance['title'] ); $instance['number_products'] = absint( $new_instance['number_products'] ); return $instance;}//display our widget function widget( $args, $instance ) { global $post; extract( $args ); echo $before_widget; $title = apply_filters( 'widget_title', $instance['title'] ); $number_products = $instance['number_products']; if ( ! empty( $title ) ) { echo $before_title . esc_html( $title ) . $after_title; };//custom query to retrieve products $args = array( 'post_type' => 'halloween-products', c08.indd 202 12/6/12 1:20 AM Publishing to the Plugin Directory ❘ 203'posts_per_page' => absint( $number_products ) );$dispProducts = new WP_Query(); $dispProducts->query( $args ); while ( $dispProducts->have_posts() ) : $dispProducts->the_post();//load options array $hween_options_arr = get_option( 'halloween_options' );//load custom meta values $hs_price = get_post_meta( $post->ID, '_halloween_product_price', true ); $hs_inventory = get_post_meta( $post->ID, '_halloween_product_inventory', true ); ?> <a href="<?php the_permalink(); ?>" rel="bookmark" title="<?php the_title_attribute(); ?> Product Information"> <?php the_title(); ?> </a> <?php echo '' .__( 'Price', 'halloween-plugin' ). ': ' .$hween_options_arr['currency_sign'] .$hs_price .'';//check if Show Inventory option is enabled if ( $hween_options_arr['show_inventory'] ) {//display the inventory metadata for this product echo '' .__( 'Stock', 'halloween-plugin' ) . ': ' .$hs_inventory .'';} echo '<hr>'; endwhile; wp_reset_postdata(); echo $after_widget;}}PUBLISHING TO THE PLUGIN DIRECTORYNow it’s time to release your plugin to the world! Releasing your plugin on WordPress.org is not a requirement, but it is the best way to get your plugin publicized and have other WordPress users download and install it. Remember that the Plugin Directory on WordPress.org is directly hooked to every installation of WordPress, so if your plugin exists in the directory then anyone running WordPress can easily download and install it. c08.indd 203 12/6/12 1:20 AM 204 ❘ CHAPTER 8 PLUGIN DEVELOPMENTRestrictions A few restrictions exist to submitting your plugin to the Plugin Directory: ➤ Plugin must be compatible with GPLv2 or any later version. ➤ Plugin must not do anything illegal or morally offensive. ➤ Must use the Subversion (SVN) repository to host your plugin. ➤ Plugin must not embed external links on the user’s site (such as a “powered by” link) without asking the plugin user’s permission. Make sure to follow these guidelines or your plugin will be removed from the Plugin Directory.Submitting Your Plugin The fi rst step is to create an account on WordPress.org if you don’t already have one. To register a new account, visit the registration page at http://wordpress.org/support/register.php. This WordPress.org account is used in the Plugin Directory as well as the support forums. After you have registered your account and signed in, it’s time to submit your plugin for inclusion in the Plugin Directory on WordPress.org. To submit your plugin, visit the Add Your Plugin page at http://wordpress.org/extend/plugins/add/. The fi rst required fi eld is the Plugin Name. The plugin name should be the exact name you want to use for your plugin. Keep in mind that the plugin name will be used as the URL in the directory. For example, if you submit a plugin named WP Brad, the URL to your plugin in the Plugin Directory will be http://wordpress.org/extend/plugins/wp-brad/. As you can see, the name you insert here is very important and cannot be changed. The second required fi eld is the Plugin Description. This fi eld should contain a detailed description about your plugin. Remember that the description is really the only information used to decide whether or not to allow your plugin in the directory. Clearly state the plugin functionality, the purpose of the plugin, and installation instructions for the plugin. The fi nal fi eld is the Plugin URL. This is not a required fi eld, but it’s highly recommended that you include a download link to your plugin. This enables the reviewer of your plugin to download and look at your plugin if needed. Again this is not a required fi eld but you are strongly encouraged to fi ll it in. After you have fi lled out all of the information, click the Send Post button to submit your plugin request. The Plugin Directory states, “Within some vaguely defi ned amount of time, someone will approve your request.” This doesn’t really tell you much, but most plugins are approved within a day or so. The fact that your plugin has been approved does not mean you are done. The next step is to upload your plugin to the Subversion Repository that has been created for it.Creating a readme.txt File One fi le that is required to submit your plugin to the Plugin Directory is readme.txt. This fi le is used to fi ll in all of the plugin information on the Plugin detail page in the Directory. WordPress c08.indd 204 12/6/12 1:20 AM Publishing to the Plugin Directory ❘ 205 has developed the readme fi le standard, which details exactly how your readme.txt fi le should be defi ned. Here’s an example readme.txt fi le: === Plugin Name === Contributors: williamsba1, messenlehner, ericlewis, jtsternberg Donate link: http://example.com/donate Tags: admin, post, images, page, widget Requires at least: 3.0 Tested up to: 3.5 Stable tag: 1.1.0.0 License: GPLv2Short description of the plugin with 150 chars max. No markup here.== Description ==This is the long description. No limit, and you can use MarkdownAdditional plugin features* Feature 1 * Feature 2 * Feature 3For support visit the [Support Forum](http://example.com/forum/ " Support Forum")== Installation ==1. Upload 'plugin-directory' to the '/wp-content/plugins/' directory 2. Activate the plugin through the 'Plugins' SubPanel in WordPress 3. Place '<?php gmp_custom_function(); ?>' in your theme templates== Frequently Asked Questions === A question that someone might have =An answer to that question.= Does this plugin work with WordPress Multisite? =Absolutely! This plugin has been tested and verified to work on the most current version of WordPress Multisite== Screenshots ==1. Screenshot of plugin settings page 2. Screenshot of plugin in action== Changelog === 1.1 = * New feature details * Bug fix details= 1.0 = c08.indd 205 12/6/12 1:20 AM 206 ❘ CHAPTER 8 PLUGIN DEVELOPMENT* First official release== Upgrade Notice === 1.1 = * Security bug fixedFor an online readme.txt example, visit the Readme Standard at http://wordpress.org/extend/ plugins/about/readme.txt.WordPress.org also features a readme.txt validator so you can verify you have a properly formatted readme.txt fi le before submitting to the Subversion directory. You can access the validator at http://wordpress.org/extend/plugins/about/validator/. Let’s break down the individual readme.txt sections: === Plugin Name === Contributors: williamsba1, messenlehner, ericlewis, jtsternberg Donate link: http://example.com/donate Tags: admin, post, images, page, widget Requires at least: 3.0 Tested up to: 3.5 Stable tag: 1.1.0.0 License: GPLv2Short description of the plugin with 150 chars max. No markup here.The Plugin Name section is one of the most important parts of your readme.txt fi le. The fi rst line lists the contributors to the plugin. This is a comma-separated list of WordPress.org usernames that helped contribute to the plugin. The donate link should be a URL to either a donate link or a web page that explains how users can donate to the plugin author. This is a great place for a PayPal donation link. Tags are a comma-separated list of tags describing your plugin. The “Requires at least” fi eld is the minimal version of WordPress required to run the plugin. If your plugin won’t run on anything prior to 3.0, then 3.0 would be the “Requires at least” value. Likewise, “Tested up to” is the latest version the plugin has been tested on. This will typically be the latest stable version of WordPress. The Stable tag is also a very important fi eld and should be the current version of the plugin. This value should always match the version number listed in the plugin header. Last is a short description of the plugin, which should be no more than 150 characters and cannot contain any markup. == Description ==This is the long description. No limit, and you can use MarkdownAdditional plugin features* Feature 1 * Feature 2 * Feature 3For support visit the [Support Forum](http://example.com/forum/ " Support Forum") c08.indd 206 12/6/12 1:20 AM Publishing to the Plugin Directory ❘ 207The Description section features a detailed description of your plugin. This is the default information displayed on the plugin detail page in the Plugin Directory. There is no limit to the length of the description. You can also use unordered lists, shown in the preceding example, and ordered lists in your description. Links can also be inserted. == Installation ==1. Upload 'plugin-directory' to the '/wp-content/plugins/' directory 2. Activate the plugin through the 'Plugins' SubPanel in WordPress 3. Place '<?php prowp_custom_function(); ?>' in your theme templates The Installation section details the steps involved to install a plugin. If your plugin has very specifi c installation requirements, make sure they are listed here in detail. It’s also a good idea to list the function name and shortcode that can be used with the plugin. == Frequently Asked Questions === A question that someone might have =An answer to that question.= Does this plugin work with WordPress Multisite? =Absolutely! This plugin has been tested and verified to work on the most current version of WordPress Multisite The FAQ section is the perfect place to list frequently asked questions, of course! This helps answer commonly asked questions and can eliminate many support requests. You can list multiple questions with answers, as this example shows: == Screenshots ==1. Screenshot of plugin settings page 2. Screenshot of plugin in action The Screenshots section is used to add individual screenshots of your plugin to the plugin detail page. This is actually a two-step process. The fi rst step is to list out each screenshot description in an ordered list. The next step is to place image fi les in your trunk directory (which is discussed in more detail next). These images fi le names must match the listing number. For instance, the screenshot of your settings page should be named screenshot-1.png. The screenshot of your plugin in action should be named screenshot-2.png. The fi le types accepted are png, jpg, jpeg, and gif. == Changelog === 1.1 = * New feature details * Bug fix details= 1.0 = * First official release The next section is the Changelog. This section is important for listing out what each plugin version release has added or fi xed. This is a very helpful section for anyone looking to upgrade to the latest version. It’s always nice to know exactly what is being added and fi xed to determine how critical the c08.indd 207 12/6/12 1:20 AM 208 ❘ CHAPTER 8 PLUGIN DEVELOPMENT plugin update is. A new item should be added for each version you release to the Plugin Directory, regardless of how minor that update may be. == Upgrade Notice === 1.1 = * Security bug fixed The fi nal section is the Upgrade Notice section. This section allows you to send specifi c upgrade notice messages to the WordPress user. These messages are shown on the Dashboard ➪ Updates Subpanel when a new version of your plugin is released.The readme.txt fi le can also accept arbitrary sections in the same format as the rest. This is useful for more complicated plugins that need to provide additional information. Arbitrary sections will be displayed below the built-in sections described previously.Setting Up SVN The Plugin Directory uses Subversion (SVN) for handling plugins. To publish your plugin to the directory, you’ll need to set up and confi gure an SVN client. In this example, you are going to use TortoiseSVN for Windows. TortoiseSVN is a free GUI client interface for SVN. For a list of additional SVN clients for different platforms visit http://subversion.apache.org/.First you’ll need to download the appropriate installer at http://tortoisesvn.net/downloads .html. After installing TortoiseSVN, you’ll need to reboot your computer. The next step is to create a new directory on your computer to store your plugin fi les. It is recommended that you make a folder to store all of your plugins in, such as c:\projects\wordpress-plugins. This makes it much easier going forward if you create and release multiple plugins to WordPress.org.Next, navigate to your new wordpress-plugins directory and create a new directory for your plugin. Right-click this new folder to pull up a context menu. You’ll notice the new TortoiseSVN options listed: SVN Checkout and ToirtoiseSVN. Select SVN Checkout and a dialog box appears, as shown in Figure 8-9. The URL of the repository was provided to you in the e-mail you received when your plugin was approved. This URL should be the same as the plugin URL so in this example the URL would be http://plugins.svn.wordpress.org /wp-brad. The Checkout directory is the local folder in which to store your plugin. In this FIGURE 8-9: SVN Checkout dialog box case, you will use the new folder you created at c:\projects\wordpress-plugins\wp-brad. Make sure Checkout Depth is set to Fully Recursive. Also verify that the Revision is set to HEAD Revision. Finally, click OK. TortoiseSVN will connect to the SVN Repository for your plugin and, if all goes well, will create three new directories in your folder called branches, tags, and trunk. These three folders each serve a specifi c purpose for SVN: c08.indd 208 12/6/12 1:20 AM Publishing to the Plugin Directory ❘ 2091. Branches — Every time a new major version is released, it gets a branch. This allows for bug fi xes without releasing new functionality from trunk. 2. Tags — Every time a new version is released, you’ll make a new tag for it. 3. Trunk — Main development area. The next major release of code lives here. Now that you’ve connected to your plugin’s SVN Repository, you need to move your plugin fi les to the trunk directory. Remember to also place your readme.txt fi le and any screenshots, includes, and so on in the trunk directory for your plugin. Remember that you’re just staging the plugin fi les to publish to the plugin directory. Publishing the fi les to WordPress.org is covered in the next section.Once you’ve verifi ed all of the plugin fi les are in trunk, you are ready to publish your plugin to the Plugin Directory!Publishing to the Plugin Directory Publishing your plugin to the Plugin Directory is a two-step process. First you need to SVN Commit the trunk folder to your SVN Repository. Second, you need to tag your plugin release. Once both steps have been completed, your new plugin will appear in the Plugin Directory within about 15 minutes.To commit your plugin trunk, simply right-click the trunk folder and select SVN Commit. You’ll be presented with a dialog box to enter a log message and to select which fi les to commit to the trunk. Fill in a brief log message, such as “Adding WP-Brad 1.1,” and select all of the fi les you want to commit. TortoiseSVN will automatically select all fi les that have changed so you probably won’t need to change this. Next, click OK and you will be prompted to enter a username and password. This is the username and password you created on WordPress.org. Next, you need to tag your plugin version. To tag your plugin version, simply right-click the trunk directory and select TortoiseSVN ➪ Branch/tag from the context menu. In the dialog box that appears, fi ll in the path to your tag directory. Using this example, the URL would be http:// plugins.svn.wordpress.org/wp-brad/tags/1.1.0.0/. This tag version should match the stable tag in your plugin’s readme.txt fi le — in your case, version 1.1.0.0. Also type in a log message, such as “tagging version 1.1.0.0” and verify that “HEAD revision in the repository” is selected for the Create Copy option. Click OK and your plugin will create a new directory in your tags folder for version 1.1.0.0 with the appropriate plugin fi les. That’s it! If everything worked successfully, your plugin should appear in the Plugin Directory within about 15 minutes. Once your plugin is successfully published you’ll want to verify that all of the information is correct. One way to verify that your plugin was published successfully is to visit the Subversion URL, which for this example would be http://plugins.svn.wordpress.org/wp- brad/. Here you can ensure the trunk and tag directories were uploaded successfully. After 15 minutes, you can also verify your plugin by visiting the offi cial Plugin Directory page at http://www.wordpress.org/extend/plugins/wp-brad. If you need to make any changes to your readme.txt fi le, simply edit it locally in your trunk folder, right-click the fi le, and click SVN Commit. c08.indd 209 12/6/12 1:20 AM 210 ❘ CHAPTER 8 PLUGIN DEVELOPMENTReleasing a New Version A great feature of WordPress plugins is that you can easily release updates for your plugins in the Plugin Directory. When a new plugin version is released, a notice is displayed on any WordPress site that currently has that plugin uploaded to its server, whether or not it is activated. The user can use the automatic upgrade process to easily upgrade the plugin to the latest version. This is especially important if there are security patches in your plugin to help keep WordPress secure.To release a new plugin version, make sure you copy the updated plugin fi les to the /trunk directory you set up earlier. This folder should contain all fi les for the updated plugin version. Once you have verifi ed that all of the updates plugin fi les exist, simply right-click the trunk directory and select SVN Commit. Remember to type in a brief message such as “Committing version 1.2.” TortoiseSVN should have already selected all of the fi les that have changed, but if not, select all of the fi les you want to publish and click OK.The fi nal step is to tag your new version. To tag your new release, right-click the trunk directory and select TortoiseSVN ➪ Branch/tag. For this example, the URL would be http://plugins.svn. wordpress.org/wp-brad/tags/1.2.0.0/. Remember to write a brief log entry such as “Tagging version 1.2” and click OK. That’s it! Your new plugin version will be published in the Plugin Directory within 15 minutes. After the new version has been released, your plugin will appear at the top of the Recently Updated Plugins list on WordPress.org. The WordPress Plugin Directory is a great source for inspiration and reference when building custom plugins. Don’t be scared to look at another plugin source code for reference. Find a plugin that functions similarly to what you want and see how the plugin author structured the code or used hooks to interpose his or her plugin ideas in the WordPress core processing.SUMMARYIn this chapter you learned WordPress plugin packaging including the required plugin header, including a WordPress compatible software license with your plugin, and activating and deactivating functions. You also covered very important data validation and sanitization for plugin security. The chapter also covered powerful hooks, plugin setting options, and multiple ways to integrate your plugins into WordPress. Plugins are only half of the WordPress extensibility story, giving you the power to add custom functions and event-driving processing to your site. If you want to change the look and feel of your site, change the way in which WordPress displays posts, or provide slots for those widgets you created, you’ll want to extend WordPress through theme development which is the focus of chapter 9. c08.indd 210 12/6/12 1:20 AM 9 Theme DevelopmentWHAT’S IN THIS CHAPTER?➤ Understanding the various fi les and templates that constitute a theme ➤ Modifying an existing theme to meet your own needs ➤ Identify the diff erent reasons to use a project theme or a child theme ➤ Creating a new theme based on the Twenty Eleven theme Content is king, right? That is certainly true. Nothing is going to drive visitors to your site, and keep them coming back, except for your content. Even if you have the best content on the Internet for your topic, you have to present it to the reader, the browser, and to the search engines so that your content can be consumed. That’s where themes come in. Themes control the presentation layer of your site, including both the user experience and how it is offered to the consumer. It also controls the logic that determines which type of page and, therefore, which type of loop is to be used. This chapter reviews how to install a theme on your website and then takes you through the various aspects of a theme and how they apply to the presentation of your content. You will also review different strategies for creating your theme, whether specifi cally for a project, or as an adaptation of a theme framework. By the end of this chapter, you will have an understanding of theme functionality and a solid foundation on which to build your own custom project or child themes from scratch for use in your own projects.WHY USE A THEME?Your website theme is essentially the face of your website. It’s what makes the fi rst impression on your visitor. Even though surely none of us is shallow enough to judge a book simply by its cover, if your website has valuable content but your theme makes the content hard to read, c09.indd 211 12/6/12 1:20 AM 212 ❘ CHAPTER 9 THEME DEVELOPMENT hard to fi nd, or generally inaccessible in any way, or your site is slow to load, not to mention downright ugly, you have probably lost that visitor. You may never have had that visitor to lose. The theme accomplishes many things for your website. Generally, people think of the theme as the appearance of your site. It is the look and feel that gives your website that certain style or fl air. It is the x-factor that gives your site a personality and makes your site stand out from the crowd. Your theme is all that; a picture really is worth a thousand words. But this is simply the graphical aspect of your site; your theme is so much more than the cohesive marketing and branding facade. Your theme encompasses the entire user experience and more. It controls what content gets rendered, including any error conditions. Your theme converts your content and look and feel into the raw HTML that is delivered to the browser through its various templates. In general, that’s what this chapter is about: using your theme to structure and control the content delivery and the overall personality of your website. Your theme also has other functions, including user experience and search engine optimization, which are addressed in later chapters.INSTALLING A THEMEStarting back in 2010, WordPress began shipping a new default theme each year. The Twenty Ten theme, released in — you guessed it, 2010 — was the fi rst to replace the venerable Kubrick theme that had been around since 2005. Last year, Automattic released the Twenty Eleven theme as the new default, and the new Twenty Twelve theme is expected to release with WordPress 3.5. These default themes are all pretty solid themes to use for your site, but they are the defaults. That means you see them on many sites across the web. Being unique, or custom, may or may not be important to you or your goals, but for the sake of this chapter, pretend it is and you don’t want to use a stock, out-of-the box theme. How do you make WordPress use a new theme? First, you either have to fi nd one you like or make one. Countless WordPress theme resources are available, and they all vary in quality. It is best to try some out and see how they work with your content and if they match the personality and branding you want your site to convey. You have two simple ways to activate a new theme on your website. There is the traditional FTP installation, and as of WordPress 2.8 there is a new integrated theme browser and installer. The Theme Browser is limited in that it allows you to install themes only from the sanctioned WordPress Theme Directory on WordPress.org. This is not inherently bad because plenty of solid, good-looking themes are in the Theme Directory and they are all GPL licensed and free (two of the requirements for being listed in the Directory). However, the Directory is a limited market; heaps of other sites offer valuable WordPress themes, still of varying quality, both for free and for premiums. In order to install these non-Directory themes, you will have to use the FTP method.FTP Installation File Transfer Protocol, or FTP, is the old standby for transferring fi les from your local workstation to the server. If your host supports it, you should use a secure form of transfer, such as SFTP or SCP, to move the fi les, but the concepts here are similar. c09.indd 212 12/6/12 1:21 AM What Is a Theme? ❘ 213Download the theme package that you would like to try to your local computer and unzip it to a local directory. If you have shell access on your server, you can unzip on the server to save in transfer time. Using your FTP client, connect to your web server. FTP or copy the fi les into your themes directory of your site. Your themes folder is located in /example.com/wp-content/themes/. Once your theme fi les are on the server, log in to your site’s WordPress Control Panel. Select Appearance, select your theme to preview it, and then activate it. Your website is now using the new theme.Theme Installer WordPress 2.8 introduced a new Theme Installer. Currently this is offered as new tab on your Themes Control Panel. The Manage Themes tab reveals which themes are currently available to your WordPress installation. The second tab, Install Themes, allows the site administrator (or anyone else with proper permissions) to search and fi lter the online WordPress Theme Directory for existing published themes. All themes in the Directory are subject to certain conditions in order to be listed; most notably, they must be licensed to be GPL-compatible. This new Theme Installer is pretty slick. You simply work the fi lters and search terms to browse the Directory. Browse the thumbnail screenshots until you fi nd one you like. Then you can either click Install Now to make it available to your current WordPress installation. Or you can preview the theme in a larger format with a variety of HTML elements displayed for you to examine the CSS styling. Finally, you can read the theme details and user star ratings by clicking the Details link. On a development system running Microsoft Windows 7 and WAMP, this just works, which is a little disconcerting. It is a permissions issue in your Webroot. Although this raises some concerns about what else could so easily be installed on the site, in this case, it is just a development machine, and the convenience of being able to test drive new themes outweighs the concerns. Trying the Theme Installer on a production server for a WordPress site running on Ubuntu Linux may yield different results. After selecting an appropriate obnoxious theme to try out, the Theme Installer asks for FTP credentials to put the fi les on the server, in this case because the fi le security permissions on the production server are properly set for production and to not allow this sort of thing. Again, there is some concern about the actual security implications of giving out FTP credentials that are required to proceed. This is similar to how the WordPress core updates and plugin updates work. See Chapter 13 on securing your WordPress installation for information about directory permissions. In short, the Theme Installer is really slick and convenient for development to test out new themes, but because of possible security implications, carefully consider its use in a production environment. The balance of convenience and security is often a diffi cult choice.WHAT IS A THEME?What actually makes up a theme? You have an idea of what themes do, but how do they do it and what’s really involved? As previously mentioned, a theme does several things, including structuring your content and providing the personality of your website. This is done through a combination of c09.indd 213 12/6/12 1:21 AM 214 ❘ CHAPTER 9 THEME DEVELOPMENT fi les and fi le types. You will notice a mix of PHP fi les, CSS fi les, and JavaScript files in the theme. A good WordPress theme keeps the style, which is CSS, separate from the structure and logic, which make up the PHP fi les. Although there are always reasons for breaking the rules, striving to keep these separate will improve the maintainability and effi ciency of your theme. Each theme has variations on these fi les and each theme’s fi les are different.Template Files Template fi les are the meat of your theme. Template fi les are PHP code fi les that control what content is shown to your visitor. These fi les also generate the HTML for the browser to control how your content is shown. WordPress actually decides which template fi le to use based on the content requested. Certain template fi les are used for different tasks. At first glance, the quantity of template fi les in a theme can be daunting. Although each theme is different, some have only a couple of fi les, while others can be very complex. After you learn the different fi les involved in a theme, you will review the template hierarchy, which is the mechanism WordPress uses to determine which templates to use when. This template hierarchy, covered later in this chapter and the numerous types of template fi les available can be overwhelming when you are starting out on theme design, but you will develop an appreciation for the power of this setup. This fl exibility allows for a huge amount of control over your site and what is delivered to the browser, which is the beauty of WordPress and defi nitely one of its strongest traits.CSS WordPress themes truly strive to separate content from style. A theme developer can ignore these guidelines and create a poorly divided theme, but a good theme developer does this well. A theme must have at least one cascading style sheet. The primary style sheet for the theme must be named style.css. In addition, the fi rst few lines of this style sheet fi le must adhere to certain guidelines. These specifi c requirements are covered later in this chapter in the “Style.css” section. WordPress uses this information to determine which themes are available to the WordPress site and to make them show up in the Appearance Control Panel. If the style sheet header is not coded to the standard expectation of WordPress, it will not show up in the Control Panel. The style sheet is just what it sounds like. It is where you put all your CSS styles. How you structure it, or what you do with it, is entirely up to the theme developer. CSS development is both an art and a science and a whole topic worthy of its own discussion. This book does not cover the intricacies of CSS, but Wrox has a number of excellent CSS titles that can assist you on this topic.Images and Assets The theme probably includes some image fi les and other creative assets or JavaScript fi les such as jQuery plugins. These assets are used in your theme to give your website a special look and feel — the look you want. How these fi les are structured in your theme is up to you; generally, they are placed in a subfolder of the theme’s main directory, such as img/, images/, assets/ or js/ depending on the fi le type. One of the nice things about themes being compartmentalized and packaged as they are is that the images can be referenced with relative paths from your CSS fi le. c09.indd 214 12/6/12 1:21 AM Creating Your Own Theme ❘ 215In addition, these creative assets can be referenced from your template fi les using built-in WordPress functions such as bloginfo('stylesheet_directory'). This keeps the theme very portable, if done properly.Plugins As covered in Chapter 8, plugins contribute advanced functionality to a website. Some themes require specifi c plugins because the functionality is part of the theme’s personality, or they are needed to achieve a certain purpose in the theme. These plugins may be packaged with the theme or may require separate downloads. All plugins reside in the plugin folder. So while plugins are not directly part of the theme, they may be required to make the theme behave as the theme creator intended.CREATING YOUR OWN THEMENow you know how to install and activate a theme on your site as well as what the different aspects of the theme are. It’s time to take the next step and make your own theme. You can start a theme from scratch, but why not stand on the shoulders of giants and start with a theme that is similar to the look you want? Or, if you cannot fi nd one, start with a theme framework where most of the heavy lifting is done for you. There is no sense in reinventing the wheel, especially when you can use the power of open source software and start from working code.Project Themes vs. Child Themes Before diving in, let’s talk about theme development strategies. Essentially, there are two classes of themes used in daily development. Which kind you choose to create depends on the amount of customization and the specifi c project you are producing. The goal of this section is not to show that one is better than the other; you, as the developer, will have to determine what meets your needs and goals. Let’s fi rst discuss project themes. These are one-off themes, often a modifi cation of an existing theme to meet the specifi c needs and design goals of a single project. These could be greenfi eld project themes built entirely from scratch or they could be a fork of an existing theme that you modify for the purpose of your project. In addition, there are starter themes that are designed to be the foundation for a project theme. Sometimes these themes are called bare-bones or naked themes. They intentionally have minimal styling and function as a blank slate with just enough to get you started. The reason to choose a project theme for your project is you have full fl exibility to edit the PHP and template fi les. However, in doing so, you lose the ability to update the starter theme without steamrolling your customizations. A second option is what is called a child theme. A child theme inherits from a parent theme. That means you get all the functionality and styling of the parent theme and then override certain aspects with your child theme. A child theme can take two different approaches. If you have found a theme that mostly fi ts your project’s needs and you can make cosmetic changes or minor functionality adjustments, then this is the way to go. Another approach is to use a theme framework. Theme frameworks are much like starter themes for project themes, except they are designed to be parent themes to your child theme. Theme frameworks c09.indd 215 12/6/12 1:21 AM 216 ❘ CHAPTER 9 THEME DEVELOPMENT create the groundwork for your theme. You create a child theme of that theme framework with all your modifi cations. By using a child theme and a theme framework, you can make modifi cations to your child theme and retain the ability to update the framework as new revisions come out. You may have put it together already that technically there is a third approach. You can develop your own theme framework or parent theme to use in your own projects fi rst, and then use that to make your child theme for your specifi c project. The strategy you take really depends on your project’s goals and needs. To reiterate, every project is different and every developer is different. You will ultimately have to decide which method works for you and your project, and balance future maintainability with functionality requirements. In general, if you are modifying a theme, a child theme is the proper approach. However, in the real world (including but not limited to deadlines and budgets), project themes can offer the fl exibility you need. For the sake of going in-depth, you are going to explore a project theme in this chapter. With the basics of a project theme under your belt, you will be able to apply these principles to child themes as well. You will come back to child themes and theme frameworks at the end of this chapter for some more discussion.What to Look for in a Starter Theme Sometimes it is easiest to fi nd a theme close to what you have in mind, use this as your starter theme, and modify it. At the minimum, you can add your own logo. Of course you have to pay special attention to the licensing on the theme. Conveniently, themes in the wordpress.org Theme Directory are all GPL themes, so you can modify and use them however you desire. Things to consider when starting from a working theme include: ➤ Licensing on the original theme ➤ Code quality ➤ How much modifi cation will be required ➤ Source artwork for the creative assets You will want to make sure that you are permitted to change the source theme you are starting with. You will also want to review the code quality of the theme because you will be the one making the modifi cations going forward. Does the theme accomplish the same presentation goals as your site, template-wise; does it convey your data the way you want it conveyed? There is no point in starting with a theme that you have to completely retool, if this is the case, you’d be better off starting with a theme framework and making a child theme. Does the theme have enough CSS hooks for you to style? Was search engine optimization (SEO) a consideration when the theme was developed? How much modifi cation will be needed to meet your requirements and will you be happy with the end result? Finally, does the theme come with source art, like the original Photoshop document, for you to modify? If not, do you need it, or will you be able to re-create any assets you must have? There are many considerations when developing a new project theme or modifi ed child theme for either yourself or a client. The convenience of modifying a pre-built theme is quite a temptation when you need to get a site up and running and out the door quickly. In practice, many sites have c09.indd 216 12/6/12 1:21 AM Creating Your Own Theme: Getting Started ❘ 217 been built this way, where a client could select a stock template with a few minor modifi cations needed to quickly launch a new site. The catch is when a site goes beyond these simple modifi cations and you are stuck with modifying a poorly built theme. For that reason, even if a client likes a particular theme preview, you may fi nd it easier in the long run to rebuild a similar theme from scratch with a starter theme as the launching point.CREATING YOUR OWN THEME: GETTING STARTEDCreating your own theme can be as simple or as complicated as you want it to be. Sometimes, you merely want to change a logo or a color and it is a basic process. Often, you are creating a theme from scratch to meet a certain need or condition, or solely to obtain a specifi c design look and feel. Whatever your motivations are, this section discusses the basics for getting a new theme and site design up quickly using the Twenty Eleven theme as a foundation. This example uses Twenty Eleven because it ships with WordPress, not because it is endorsed as the best choice for a starter theme. In practice, however, it has been used both as a starter theme and a parent theme for client projects. In the next several sections, you will tour the Twenty Eleven theme as an example of the elements of a working theme. You will also take this opportunity to modify the theme into your own version with your own customizations allowing you to leave the existing Twenty Eleven theme intact. It should also be mentioned that the Twenty Eleven theme uses HTML5 elements and an HTML5 shim. HTML5 is covered in more detail in Chapter 12, but just be forewarned that while using HTML5 is becoming more and more commonplace every day, it is still on the newer edge of web technology and all browsers may not support it.Essential File: Style.css The style.css fi le is what WordPress uses to reference your theme, and this fi le is required for your theme to work. You could create a new theme with only a style sheet and index.php template fi le, although the index fi le can be empty. Using the power of WordPress’ theme hierarchy, WordPress automatically substitutes missing templates if your new theme does not have them. More on that later, but understand that a customized style sheet is what allows you to get started creating your own theme.NOTE In practice, a style.css fi le is all you need to create a new theme. See the section, “Theme Hierarchy and Child Themes,” later in the chapter.When creating your own styles.css for your new theme, the fi rst few lines are absolutely critical. These lines provide information to WordPress to use in the theme Control Panel and further reference your theme in the core. Your fi rst few lines should read as follows (substitute your information, of course):/* THEME NAME: MyTheme THEME URI: http://www.mirmillo.com/mytheme/ DESCRIPTION: Theme for my new site. Based on Twenty Eleven. c09.indd 217 12/6/12 1:21 AM 218 ❘ CHAPTER 9 THEME DEVELOPMENTVERSION: 1.0 AUTHOR: David Damstra (and friends) AUTHOR URI: http://mirmillo.com/author/ddamstra License: GNU General Public License v2 or later License URI: http://www.gnu.org/licenses/gpl-2.0.html Tags: dark, light, white, black, gray, one-column, two-columns, left-sidebar, right-sidebar, fixed-width, flexible-width, custom-background, custom-colors, custom-header, custom-menu, editor-style, featured-image-header, featured-images, full-width-template, microformats, post-formats, rtl-language-support, sticky-post, theme-options, translation-ready */The information here is pretty self-explanatory. There is an additional optional fi eld for theme hierarchy, covered later in the chapter. Make sure your theme name is unique to your installation. If you intend to release your theme for public use, either for free or for a premium, you should try to come up with a unique name to reduce naming collision in the directory and other installations. In addition, if you are deriving your theme from another theme, license permitting of course, you should uphold the license and copyright information from the original theme. Once you have addressed this required information for WordPress, the remainder of the fi le is traditional CSS and subject to the rules and structure imposed as such. To reiterate, you are making a copy of the Twenty Eleven theme and making it your own. This is not a child theme process. Child theme functionality will be covered later. In some cases, the workfl ow fi ts better if a new theme is created by copying and renaming the starter theme to a new folder and revising the style.css to refl ect the new project. This technique has pros and cons, but it works well for some teams because the foundation theme does not change often enough to warrant more complex methodologies. Plus, when you have a theme in production, you do not want a change to the parent theme to cause a cascading rendering issue in your successfully deployed site. Creating a copy and making a working theme in this new directory removes the dependency on future browser rendering testing, which is a time- and human-intensive procedure — that is, no one has automated this procedure yet. In the event that there is a substantial change to the parent theme, changes can be ported to the derivative themes on a case-by-case basis and tested as needed. Making a copy of the starter theme also enables you to create a hand-crafted CSS fi le by modifying the actual theme fi les rather than overriding the styles and carrying that additional byte baggage.Moving forward, CSS rules are written out in the style.css fi le to turn your minimal layout into the professionally designed theme you are creating. Because you are working on your own copy of Twenty Eleven, a fork of it, so to speak, you can edit your own theme’s style sheet directly. CSS coding is outside the scope of this book and if done well, is an art and skill. Again, Wrox has several great books on working with CSS.Showing Your Content: Index.php When creating your theme, you often have a chicken-and-egg problem. Maybe you are lucky and you know exactly what content is going to be published on your WordPress site, and exactly how it’s going to be structured. Maybe you even know exactly how the fi nal theme is going to look, or you’ve had a professional designer create some mock-ups for you. But odds are, your site is going to c09.indd 218 12/6/12 1:21 AM Creating Your Own Theme: Getting Started ❘ 219 grow organically, and to see how the design, and therefore the style sheet, is going to play out, you need to have some content to display. You can use certain stock content fi les to import into your site and work through all the styles, or you can start building your site. Theme Unit Tests and stock content fi les are covered in Chapter 3.The index.php fi le is the default template of your site. WordPress has a built-in decision engine that decides which type of information your visitor is requesting and then determines if there is a template fi le available for that information type. This hierarchy is covered later in the chapter, but the index.php template is the default, or template of last resort. If WordPress does not determine that there is a more specifi c template to use, index.php is it.Usually, the index.php fi le contains your standard loop. This is a traditional blog format where the posts are displayed in reverse chronological order. For example, the following is some of the code from Twenty Eleven’s index fi le:<?php if ( have_posts() ) : ?> <?php twentyeleven_content_nav( 'nav-above' ); ?> <?php /* Start the Loop */ ?> <?php while ( have_posts() ) : the_post(); ?> <?php get_template_part( 'content', get_post_format() ); ?> <?php endwhile; ?> <?php twentyeleven_content_nav( 'nav-below' ); ?> <?php else : ?>As covered in Chapter 5, the loop is really the heart of WordPress. It is the most important concept to grasp because this is how your content is selected and ordered for publishing. You may look at the preceding code snippet and notice that the loop is really a small part of the code and that the content of the posts is not even being rendered in HTML.And you would be correct. The preceding snippet uses the get_template_part() function, which was introduced in WordPress 3.0. This is a WordPress function that is very similar to PHP’s include() and require() functions, but it is more powerful because it is WordPress-specifi c. The get_template_part() function allows the theme developer to pull out specifi c code components for reuse, or for replacing in child themes. In the preceding example, WordPress is looking for a specifi c PHP fi le to include as the rendering of the posts in the HTML. This is actually a fairly complex example because it uses the get_post_format() function to fi ll in the second parameter of the include. Get_post_format() will do exactly what it says and return the format of the post. Post formats are covered a little later in this chapter. For the sake of this example, just know that if the post were marked as an image, this function would return image, or if it were published as a traditional post or marked as standard in the Add New Post Panel, it would return “false.”The get_template_part() function will look for the template fi le in the current theme directory, fi rst as the specifi c version using the second parameter and then for the generic version ignoring the second parameter. That is, if you use the following code in your theme:<?php get_template_part( 'content', 'index' ); ?> c09.indd 219 12/6/12 1:21 AM 220 ❘ CHAPTER 9 THEME DEVELOPMENTWordPress will fi rst look for fi le named content-index.php in your theme folder and, if it cannot fi nd that fi le, will settle for content.php. If you are creating a child theme and neither of the preceding fi les is found, WordPress will continue the search in the parent theme folder. In the Twenty Eleven example, the get_post_format() function is performing as a switch to pull in the desired content template for the appropriate post format. You will notice in the Twenty Eleven theme that there are many content templates — one for each post format type. This allows the theme developer to control how the different post formats are rendered in the browser. Another advantage of this tactic is breaking your code into smaller, manageable portions. You’ll fi nd this compartmentalization makes it easier to debug should you develop any problems with future changes, or need to add new functionality.Showing Your Content in Diff erent Ways: Index.php The index.php fi le is really the most important template fi le in your theme. Although you cannot have an active theme in WordPress without styles.css — because that is how WordPress knows you have the theme available — index.php does the heavy lifting. In the early days of WordPress, the index template was the only template. The whole theme was just this one fi le, and it was really just the loop. That worked fi ne for WordPress when you used it as a traditional blog and this bloggy look is probably why WordPress is still derided as a blog engine. Hopefully you are reading this book because you know WordPress can be so much more, or if you did not know, that you are realizing it now. Your index template is very important; this cannot be stressed enough. It is the template of last resort that WordPress will use when it cannot fi nd a more specifi c one to use (see the section, “Template Hierarchy,” later in the chapter.) Nevertheless, your index fi le does not have to be a single loop showing your most recent posts. That is very traditional, and may work well for your site, but you can branch out. Your index fi le can be structured in so many different ways, it is truly limitless. It could contain multiple different loops from different tags or categories, or it could contain no loops at all. The index template could function as your error page, where you have more specifi c templates for every other piece of content in your site.CREATING YOUR OWN THEME: DRYAs just discussed, these are the basics; WordPress requires a style.css fi le with properly formatted header information, and a theme must have an index.php template. Now you want to expand your theme to use more template fi les and capitalize on the robust theme engine found in WordPress. A good developer knows that you do not want to repeat code in multiple places; it is a bad design and gives your code one of those nasty smells. (You knew that right?) The code smell is called Don’t Repeat Yourself (DRY) and is, in fact, one of the easiest smells to get a whiff of and avoid. When you fi nd yourself tempted to cut and paste a code block from one template to another, that should be your fi rst whiff. Here is your opportunity to break out your templates into reusable parts. There c09.indd 220 12/6/12 1:21 AM Creating Your Own Theme: DRY ❘ 221 are three obvious places where you can do this because you will reuse these components on nearly all pages on your site to give it that cohesive look and feel and structure. The header, the footer, and the sidebar information is essentially the same on all pages. You will also learn how to tweak these included fi les with additional logic to handle design exceptions.Header.php You may think this fi le is a misnamed, but it is the standard name of this fi le that WordPress looks for. The header.php fi le includes everything at the top of your rendered page, up to the content area. This can be confusing because a properly formatted HTML document includes its own <head> information, which has its own special requirements. This header.php template fi le includes the HTML head, but it also includes the start of the HTML document and usually includes the site logo and navigation, assuming you are using an across-the-top horizontal navigation scheme. It can also include any additional elements at the top of your page, such as secondary navigation or a search area. Because this fi le includes so much more than the HTML header, the tendency is to take the printing term and call this area the nameplate, as in the nameplate of a newspaper or magazine. However, stick with tradition and leave the fi le name header.php in order to remain compatible with the built-in functionality of WordPress. When creating your header template fi le, a very important WordPress function must be included: wp_head(). This is a hook for WordPress to be able to attach certain functionality into your site header and is also used by plugins. The wp_head() function is dropped in your HTML <head> node and is critical to the long-term compatibility and functionality of your theme so make sure this is included.Now that you have broken out the nameplate section of your pages into the separate header.php template, if you were building a theme complete from scratch you would need to adjust your index.php fi le to include it. You could use the traditional PHP include or require family of functions, but the WordPress core functionality has a handy function to get around the theme paths. This is similar to the get_template_part() function discussed earlier, but there is a specifi c function for the header template. At the top of your index.php (and subsequent template fi les discussed later) simply add the following code:<?php get_header() ?>This function automatically includes the fi lename header.php from the current theme’s directory into the current fi le for rendering. This function does not have any additional functionality over a PHP include besides determining the correct include path for you, but it is much more readable when working on a theme.Optionally, you could split out additional components from your header.php fi le and include them back in with PHP includes. Occasionally, if a site has a particularly long or complex global navigation, it is broken out for inclusion. In practice, working on smaller fi les is easier for editing because each template fi le has a specifi c function and reduces the complexity of debugging. c09.indd 221 12/6/12 1:21 AM 222 ❘ CHAPTER 9 THEME DEVELOPMENTNOTE In a past life, one of the authors was called in to work on a web application where the entire application was created in a single fi le and the functionality was handled by triggering specifi c functions. Although the functions were nicely broken out, any time the application had to be debugged, the error messages were nearly meaningless. Although the line number would change (and skyrocket into the multiple thousands) they all occurred in index.php and inevitably the whole application had to be traced to determine what happened. Imagine how much easier it would be to troubleshoot a problem on the application if the error message indicated that the error took place in a 100-line navigation fi le, rather than a 10,000-line complete application fi le. Everyone writes bad code in their careers, and certainly we (the authors) are no exception, although none of us wrote this atrocity. What we are saying is: do yourself a favor and break code into smaller, manageable fi les whenever possible.Footer.php In the same vein as the header.php fi le, everything below your content area should be separated out into a footer fi le. The nature of footer fi les has changed recently. Historically they have been the copyright and contact information, but in recent years, this real estate has been expanded to include additional navigation options and information relevant to your site. Most modern themes, including Twenty Eleven, include widget areas in the footer for customizable content. Widget areas are discussed later in this chapter. What you put in your footer is up to you, but because it remains by and large the same on every page, it is a prime candidate for breaking out into a separate include.Again, make sure you incorporate the wp_foot() function into your footer template. This function allows WordPress to inject any necessary information from your active plugins and, as a rule, will include your </body></html> closing tags. Similar to the way your header template is included, WordPress offers the same functionality for your footer information with its own special include function. At the bottom of your template fi les, add the following code:<?php get_footer() ?> Sidebar.php Another candidate for breaking out is the sidebar, which is everything to the right or left of your content. Your sidebar could include the navigation of your site, if you have elected a vertical navigation scheme, or perhaps less important supporting information for your site content. c09.indd 222 12/6/12 1:21 AM Creating Your Own Theme: DRY ❘ 223The Twenty Eleven theme allows for either a right or left sidebar using the same sidebar.php fi le and places it with CSS. However, you could have multiple sidebar fi les for each column or specifi c sidebars for different pages. You need to consider a number of different issues when working with sidebars. You have to decide fi rst how many sidebars you are going to have. Second, you have to decide if they are going to be static sidebars, widgetized sidebars, or a hybrid. Finally, you have to determine how the HTML is structured so that you can make the CSS put the sidebars in the correct spots. Then you have to test in your target browsers and in all likelihood start over. Such is the life of the <a href="/tags/Web_developer/" rel="tag">web developer</a>. As mentioned, the Twenty Eleven theme’s stock sidebars are both the same fi le, whether on the right or left, and are fully widgetized. This enables you to sketch up a site with relative ease and use the WordPress Control Panel to place widgets as needed.In your template fi les, place the following code to include the sidebar.php fi le:<?php get_sidebar(); ?>Sometimes having both sidebars in the same fi le does not pan out in the design, or more likely, the CSS. Or, you have broken out the sidebars into individual fi les for each sidebar location. For whatever reason, you can create two sidebar fi les for the traditional left and right places. For example,<?php get_sidebar('right'); ?> gets the fi le named sidebar-right.php, as indicated in the parameter of the function call, and includes it in the appropriate place. Again, this is similar to the get_template_part() function but is specifi cally designed for sidebars and is much more readable in the code. More advanced theme frameworks have multiple sidebars that deviate from the common notion that a sidebar is only vertical space on the left and right of your content. Some of these theme frameworks have what are essentially sidebars above, below, and even in the middle of the post loops. Having multiple widgetized areas like this transfers some power to the site administrator who can now place WordPress widgets all over the layout of the page. An important consideration when working with sidebars is keeping the balance between what portions are widgetized — meaning they can be controlled and managed by the content creator in the Control Panel — and what portions are hard-coded in PHP into the template fi le. Widgets can be very powerful, especially with many of the plugins that are available. But there are also cases where PHP code in the template fi le will get the job done and the content does not need to be updated by the administrator or is using built-in WordPress functionality to keep itself updated. Keeping this balance right is a developer decision.Deviations from the Norm: Conditional Tags You have been a good developer and broken out all your repeating code snippets into their own templates or inclusion fi les. Good job, but the marketing director just called, and even though the c09.indd 223 12/6/12 1:21 AM 224 ❘ CHAPTER 9 THEME DEVELOPMENT site is almost done, and he signed off on the design, he forgot to tell you that all the pages and posts in the Ponies category are supposed to have a pretty rainbow in the nameplate next to the site’s logo. Personal taste aside, this sucks, because you just made all the header.php fi les the same, and now only a handful of them need some special consideration. As with all things open source, there are many ways to handle this situation. You could probably handle such a simple example with some well-crafted CSS and the theme’s body class alone. Alternatively, you could create a whole category template fi le (discussed later) to style just this category. But because you’re dealing with only a tiny element, it seems like overkill to create a whole new template fi le. But wait — all is not lost. WordPress developers have had to deal with marketing directors before and knew this type of situation would come up eventually, which is why they included conditional tags. WordPress has many conditional tags built in, and covering each one is outside the scope of this book, not to mention particularly boring. But rest assured — these conditional tags exist and can address specifi c needs such as what type of page is being viewed, or the meta information about the content on the page.To appease the marketing director, you might include something like this in the header.php fi le:<header id="branding" role="banner"> <hgroup> <h1 id="site-title"><a href="<?php echo esc_url( home_url( '/' ) ); ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a> </h1> <?php if (is_category('Ponies')) { ?> // overlay a pretty rainbow on the logo for the ponies category /img/rainbow.png" alt="OMG! Ponies! " /> <?php } ?> <h2 id="site-description"><?php bloginfo( 'description' ); ?></h2> </hgroup> ... </header>Now, any time the category of the content of the current page is in the Ponies category, your header also includes the rainbow.png. With PNG’s alpha transparency, it actually turns out nicely. This example only works for the category pages and not for the individual single posts pages in the Ponies category.CREATING YOUR OWN THEME: CONTENT DISPLAYA good theme enhances the content on your site. Not only is it visually appealing, suitable for the nature of the site, and brand appropriate, but the theme should also structure the content properly. WordPress has a variety of different templates and functionality to meet the needs of every site type. c09.indd 224 12/6/12 1:21 AM Creating Your Own Theme: Content Display ❘ 225The challenge here is to uncover the best combination of template fi les to include in order to achieve the optimal organization of your content. Not all themes need to have every template fi le type, and most do not; it is best to mix and match templates to meet your needs.Customizing Your Homepage: Front-Page.php Homepage — who uses that term anymore? It sounds so 1990s, but what else should you call it? This section covers the fi rst page on your site when a visitor goes to your root URL. Apache users know that the index page of your site, the homepage if you will, is called “index.” It is usually called “default” on a Microsoft IIS server. The WordPress Control Panel refers to this as the front page; you can run with it for consistency’s sake.A theme should always have an index.php fi le because after all else, index.php is the template of last resort. What if want your front page to have a special layout, perhaps one that features something about your site — product pages, for example? You do not want to mess with your index.php layout because you do not want to reinvent your entire theme just to accommodate this one special layout. Plugins and other tricks are available to handle this scenario; in fact, you can even use the WordPress Control Panel to set a static front page that is one of your existing published pages. But in this case, you are talking about a custom layout or HTML rendering, not a traditional page. The easiest way is to use the built-in template hierarchy and set a special front page by using a front-page.php template.There are actually two template fi les that can function as your front page: front-page.php or home.php. In some older themes and even in the fi rst edition of this book, home.php was the only option. With WordPress 3.0, front-page.php became the preferred template fi le name for the front page. There is a little more involved here, depending on how you set your reading preferences in the Dashboard. Later in this chapter, you will see the template hierarchy and how these two templates actually rank. Creating a special layout, and therefore template fi le, for your front page is useful when your front page is unique. By and large, creating a unique front page is a marketing tool. Some reasons for creating a unique front page include: ➤ Featuring or showcasing a product or service ➤ Featuring or showcasing other portions of your website ➤ Driving traffi c to a certain portion of your site ➤ Explanatory steps of the processes involved with your product ➤ Delineating tiered levels of service that you provide Take a look at the basic example in Figure 9-1, where the front page is showcasing products or services that the website is marketing. These products would have their own supporting pages or posts in your site. Your front page has a nice image showcase front and center with links to the individual pages. You’ll use jQuery to enhance this showcase and rotate through the images. Alternatively, you could use a different JavaScript toolkit or Adobe Flash, but jQuery is already c09.indd 225 12/6/12 1:21 AM 226 ❘ CHAPTER 9 THEME DEVELOPMENT included with WordPress and, frankly, it rocks, so why not use that. The bottom portion of the layout will include a recent news section.FIGURE 9-1: A special template fi le can make your front page look unique.If you cannot tell already, this is going to involve multiple loops. You will use the fi rst loop to create the content for the showcase. This loop will pull posts from a specifi c category or a custom post type. That way, the site admin can add and remove content from the showcase as needed, without visiting the code at all. Of course there will be certain design restrictions, such as image size and format and possibly certain conventions that must be followed in the post, but the capability to change this information in the WordPress Control Panel is a very powerful tool. The showcase loop, sometimes called slideshows, could look something like this (in this case, you are using custom post types, which are covered in Chapter 7):<div id="showcase"> <?php global $post; $args = array( 'post_type' =>'slides', 'numberposts' => -1, 'orderby' => 'rand' ); $slider_posts = get_posts($args);// show showcase only if slides exist if($slider_posts) { foreach($slider_posts as $post) : setup_postdata($post); // get image $thumbnail = wp_get_attachment_image_src(get_post_thumbnail_id(), c09.indd 226 12/6/12 1:21 AM Creating Your Own Theme: Content Display ❘ 227'home-slide'); if ($thumbnail[1] == "600" && $thumbnail[2] == "160") { //checking thumbnail dimensions in css ?> <div id="feature-<?php echo $post->ID; ?>" class="slide"> <a href="<?php the_permalink(); ?>" title="<?php the_title(); ?>"> " title="<?php the_title(); ?>" /> </a> </div> <?php } ?> <?php endforeach; ?> <?php wp_reset_postdata(); ?> <?php } ?> </div>This creates an HTML rendering, as shown in Figure 9-1.Take a look at what is happening here. The whole showcase loop is wrapped in a <div> with an ID of showcase. This is for the jQuery to hook onto later. In the PHP code, you are creating a custom query for the loop. The query is looking for custom post types called slides, which you would have previously established in the themes functions.php fi le and also set up in the WordPress Control Panel. This query is pulling all the slides from the custom post type and returning them in random order. The loop then proceeds to create <div> elements, each with a unique ID, again for jQuery and CSS hooks. The custom post type is set up to use the WordPress featured image as the slide content. This allows the site maintainer to upload the slide image that, in turn, links to a special landing page with more information in the post body. The preceding code snippet will only display the slide graphic if it is set to the specifi c dimensions, 600px wide by 160px tall in this case. Finally, countless jQuery plugins are available that can turn this now unwieldy block of content on your page into a very elegant slideshow.The bottom section could be a traditional loop similar to the index.php template stock loop. The Twenty Eleven theme does not come with either a front page or home page template built in because, when using these templates, you are already on your way to creating a custom theme. Also, this is not the only way to get this functionality. As of WordPress 2.1, you can control what is shown on your front page and set it to any static page you have created and then create a special page template to accomplish the previously described design decisions. You can also build multiple loops — one using posts in a category for the slides, the other loop excluding the category for the news. This is how you used to do it. Again, how you choose to skin this cat is one of those choices you have to make as a developer as you balance the needs of your client with the ease of maintenance for your developers.Show Your Older Posts by Date: Archive.php Eventually, if you are diligent, your site will have older content. And if you are really industrious you will be able to do those fun “One year ago on my site I told you about X” posts. Eventually, you may have copious amounts of content, so much that it is not feasible or appealing to show it all on the front page. That is, if content is being generated on a regular schedule, there will come a point in time when you will want to refer to something that is no longer on the front page or in the Recent Posts lists; this is the time when you need to delve into the vault of past content. c09.indd 227 12/6/12 1:21 AM 228 ❘ CHAPTER 9 THEME DEVELOPMENTThis is where the archive.php template steps in. You have many ways to present your older content. Harkening back to WordPress’ blogging origins, the most obvious method is to continue in reverse chronological order of your posts. If you do not have an archive template, WordPress simply uses your index template to show the older posts. The Twenty Eleven theme has an interesting take on the archive.php template that dates back to some of the original starter themes such as the Sandbox theme. This approach is very fl exible and creates date-based format visuals for the archives. Consider this code from the Twenty Eleven archive.php template:<h1 class="page-title"> <?php if ( is_day() ) : ?> <?php printf( __( 'Daily Archives: %s', 'twentyeleven' ), '' . get_the_date() . '' ); ?> <?php elseif ( is_month() ) : ?> <?php printf( __( 'Monthly Archives: %s', 'twentyeleven' ), '' . get_the_date( _x( 'F Y', 'monthly archives date format', 'twentyeleven' ) ) . '' ); ?> <?php elseif ( is_year() ) : ?> <?php printf( __( 'Yearly Archives: %s', 'twentyeleven' ), '' . get_the_date( _x( 'Y', 'yearly archives date format', 'twentyeleven' ) ) . '' ); ?> <?php else : ?> <?php _e( 'Blog Archives', 'twentyeleven' ); ?> <?php endif; ?> </h1>This code block shows how the theme’s archive template displays a unique header depending on whether the visitor is looking at the archived posts for a day, a month, or a whole year, or traversing by conventional pagination. Except for the fact that WordPress is inherently date-based, the specifi c archive template is not all that important. Although having the date information is useful when determining how recent certain information is, in reality, do you ever go back and look for posts published in May of 2007? More likely, you are looking for posts on a certain topic or fi led in a particular category or topic.Showing Only One Category: Category.php Enter the category template. The category.php template creates a loop of posts from only a specifi c category. The category template is invoked when a visitor hits a specifi c URL with the category name in it. This could be something like http://example.com/category/zombies. In the category.php template, WordPress has already determined that your visitor is looking for posts in the particular category requests, so the default loop automatically makes this query for you, no special interaction required. When you use this template, you can generically display category posts and information, this is exactly how the Twenty Eleven theme is set up. For example, the Twenty Eleven theme places a header and category explanation information pulled from the category description, if it is available:<header class="page-header"> <h1 class="page-title"><?php c09.indd 228 12/6/12 1:21 AM Creating Your Own Theme: Content Display ❘ 229 printf( __( 'Category Archives: %s', 'twentyeleven' ), '' . single_cat_title( '', false ) . '' ); ?> </h1> <?php $category_description = category_description(); if ( ! empty( $category_description ) ) echo apply_filters( 'category_archive_meta', '<div class="category-archive-meta">' . $category_description . '</div>' ); ?> </header>This covers the default category case, which is a nice default fallback template to have. But what if you want to make each category template have a unique look — for example, a color scheme or an icon? Assume your pony-and-rainbow fascinated marketing director now wants a Zombie category. Instead of using conditional tags, you can make a specifi c category template. Following the template hierarchy, WordPress will look to see if there exists a category template that is specifi c to the category requested in the URL. If you have not noticed yet, WordPress works from most specifi c to least specifi c until it fi nds the proper template. WordPress will select the most specifi c template for the type of information requested and work toward the more generic templates until it defaults to the index.php template. This is a critical aspect to learn when deciding on your theme templates, and it’s something you will review again.For the marketing director, you can make a category-3.php template, for example, because the Zombies category has an ID of 3. The easiest way to fi nd a category ID number is to hover over the category name in the Edit Category Control Panel and look in the status bar at the bottom of the browser window, as shown in Figure 9-2.FIGURE 9-2: Hover over the category name in the Control Panel to see the category ID in the status bar. c09.indd 229 12/6/12 1:21 AM 230 ❘ CHAPTER 9 THEME DEVELOPMENTThere is a little bit of a chicken-and-egg problem when you want to create a category template for a specifi c category. In order to name the template fi le correctly, you must create the category first to get the category ID. Lucky for you, there is another way. Since WordPress 2.9, users have been able to make category templates that use the slug. And the slug template fi le is preferred by WordPress over the ID-based one. So to avoid the chicken-and-egg problem, you can create the category fi rst and assign it a slug, in this case zombies. If you have this planned out ahead of time, you can make a category template fi le called category-zombies.php and be off to the races. These specifi c category templates work exactly the same as the generic category templates and pull the posts for that category automatically. Technically, it works the other way around: WordPress already knows which posts it is going to show you; it is just determining how to show them to you. What you are gaining with using a specifi c category template is the fl exibility to style each category individually. You have probably noticed by now that with WordPress there is always more than one way to do something. In the simple example of the marketing director, you can solve his problem with conditional tags or category-specifi c templates, or most likely, you can meet his requirements by using CSS because most themes have rich CSS hooks. But the extensibility of this feature is the killer aspect. Just knowing that WordPress has the feature built in will save you one day.Show Posts of a Specifi c Tag: Tag.php The tag.php template functions nearly identically to the category.php template. It is invoked when a visitor requests a specifi c tag. This template is only benefi cial if you are actively tagging the content on your site. Most likely, you are assigning categories to content because that is a natural human organization structure, but tagging is not as clear-cut and often feels like an additional step. Nevertheless, if you are diligent in tagging content, a tag template is a nice addition to your layouts and can be benefi cial to cross-pollinate posts with related content. When this template is called, the loop automatically fi lls with posts of a particular tag for rendering. For a more in-depth look at how the loop actually works, refer to Chapter 5. Likewise, you can create a template for a specifi c tag. As with categories, you can use either the tag’s ID or slug to make the template fi le. If you want a special template for the Zombies tag, you use the slug of the tag to create a new template titled tag-zombies.php. You need to verify the tag’s slug on the Manage Tags Control Panel. Using the category and tag templates may not be the way you envisioned your content being viewed, especially if you are using WordPress more as a content management system. However, simply including these templates delivers free functionality and customizability from the WordPress core. These templates enable your visitors to explore your content in different ways and perhaps add a little stickiness to your site because your content is viewed in new and interesting ways. Categories and tags group related content and using these templates create an organic presentation for discovery of your site. Do not brush these templates off as simply reverse chronological listings of related content, such as an archives page. Envision creative ways to present your data; because you have visitors who are interested in at least some of your content, why not expose them to related items? c09.indd 230 12/6/12 1:21 AM Creating Your Own Theme: Content Display ❘ 231Other Archival Templates With that in mind, WordPress’ archival templates really bloomed recently. In addition to the templates discussed previously, you can also create special archive templates for custom taxonomies or custom post types. Although these templates fall in the archival template hierarchy, you can really think of any of these views as just groupings on a certain aspect of the content. If you have custom post types set up in your theme or content, as you did with the slides in the showcase example previously in this chapter, you can have custom archive page templates for those, too. This template fi le has a slightly different naming convention than the rest. For the slides, you would create a template fi le called archive-slides.php where slides is the custom post type’s name. Likewise, if you are employing custom taxonomies in your theme, you can make custom archive templates for both the taxonomy and the specifi c term. WordPress will choose the most specifi c template fi le it can, so the term templates will be chosen before the general taxonomy templates. Custom post types and custom taxonomies were covered in depth in Chapter 7.How to Show a Single Post: Single.php You have set the bait with a great post headline, something witty and engaging. After the nibble, you set the hook with your excerpt of the post, and now you caught the visitor. He has clicked through to read the rest of the article.The single.php template view is most likely the landing page on your site when a visitor arrives via a search engine. Assuming you have great content, the search engine will rank the explanatory page of your site higher than the index page, which only lists the excerpt. Therefore, it is best to invest some time in this template because it is very commonly viewed. Enhancing this template with related posts and other teaser content only increases the possibility of enticing a visitor to further explore your site, bookmark it, subscribe to your feeds, or best of all, link back to you. All of these events increase your search engine respectability.You can display the full content of a single post with the single.php template fi le. WordPress has decided that the visitor has requested the full content of a single post; thus this template does not need to contain a loop, but simply a call to the the_post() function to get the data from the database. If you look at the Twenty Eleven theme, you will notice that the single.php template does, in fact, use a loop and the get_content_part() function to maintain consistency with the other templates, but because only one post is being shown, this is superfl uous. If you have a very long post, you can break it up among several pages by using the built-in WordPress functionality or special plugins. Internet users have very mixed feelings on this. Although general guidelines and studies have shown certain line lengths and content lengths improve readability, some vocal visitors detest the load time wait when paginating. This is a design choice based on your content type and site design. Adding links that are related to this post is a great way to entice visitors to explore your site more. Several plugins add related content to the bottom of a single post page or scan your content for keywords and links. In practice, you will have to try these out and see how they work with your site. c09.indd 231 12/6/12 1:21 AM 232 ❘ CHAPTER 9 THEME DEVELOPMENTAlternatively, the poor man’s solution is to add a simple category or tag loop to grab some related- topic posts to the bottom of the page. It could be something as simple as this:<h2>Other posts in this category</h2> <ul id="related"> <?php $category = get_the_category(); $my_query = new WP_Query("category_name=".$category[0]->name." &showposts=5&orderby=rand"); while ($my_query->have_posts()) : $my_query->the_post(); echo '<li><a href="'. $post->permalink.'">"' . $post->post_title .'"</a> </li>'; endwhile; ?> </ul>Here you are taking fi ve random posts from the fi rst category of the current post. It’s not the most sophisticated method, but it is a simple way to show some related content links on the single post view. Another option is to show additional posts by the same author:<h2>Other posts by this author</h2> <ul id="related"> <?php $author = get_the_author_meta('id'); $my_query = new WP_Query("author=".$author&showposts=5&orderby=rand"); while ($my_query->have_posts()) : $my_query->the_post(); echo '<li><a href="'. $post->permalink.'">"' . $post->post_title .'"</a> </li>'; endwhile; ?> </ul>While having a single single.php template will suffi ce for most sites, WordPress does offer some more customizability for handling the individual custom post types. Using the slideshow showcase example from before, instead of rendering the clicked through landing page using single.php, you could create a special single-slide.php template. This template might leverage the featured image or other custom fi elds to make it more enticing or actionable.Display a Page: Page.php When you’re using WordPress as a content management system, you have to make some decisions such as whether to use pages or posts. This is like cats or dogs — people have strong feelings about each. For the most part, this chapter has been talking about posts and custom post types. When working with a client, you generally create hybrid designs that use both pages and posts. Posts are used for temporal-based items, such as news and promotions, whereas pages are used for static information that does not change very often, such as products or services. Product pages are then augmented with related posts. This gives the client the benefi t of using the posts facets of the website to drive traffi c to the static product pages. c09.indd 232 12/6/12 1:21 AM Creating Your Own Theme: Content Display ❘ 233The page.php template works essentially the same as the single post template. There is no loop — unless you have created a special page template, but technically that is a different template fi le — only the call to the_post(). Yes, this is the same function as in single.php. WordPress considers the posts and pages to be fundamentally the same type of content and the_post() gathers the content from the database. As with previous examples, you can also have specifi c page templates for specifi c pages based on the ID of the page or the page’s slug. These follow the same pattern as before. In addition, you can also have custom page templates that you can assign to any page on your site, but you’ll cover this in more depth later in this chapter.Display Post Attachments: Attachment.php To be honest, we (the authors) do not think we’ve ever used these template fi les in a production website intentionally. First introduced with WordPress 2.5, image.php was a special template just for showing — you guessed it — images from your gallery. Since then, this branch of the template hierarchy has grown and generalized to show any of the attachments you might add to a post based on MIME type. Many themes do not even have this set of templates; the Twenty Eleven theme includes an image.php but not an attachment.php template. In essence, this template works very similarly to single.php, so much so that single.php is the next default if this template does not exist in your theme.The most common use for this template is to create an image.php template. This template provides a special template strictly for viewing your media gallery. A gallery can contain many different types of media; that is, it is not limited to images. This template will be called for any media item, unless there is a more specifi c match, and usually includes a description of the media and comment functionality. A great use of this template fi le would be for a portfolio site, such as a photography studio or another artistic collection. Again, this template functions nearly identically to the single post template, with slight variation to render an image rather than a paragraph. Similarly, template types can be used with media types other than images. You could create templates for video, audio, or applications; however, these would probably be very specifi c use cases, and in the wild you would rarely see or need these templates unless you were creating a specifi c niche website.Template Hierarchy With all these template fi les to choose from, how does WordPress decide which one to use? The WordPress core is pretty smart in this regard. Based on the URL, WordPress determines what type of content is being requested and can make a starting determination. Then WordPress works out the specifi city of the template to be used, using the most specifi c template that matches the criteria fi rst, and falling back to more general templates until it fi nds a match. This system works well, in that it is fault tolerant by always cascading back to index.php but extremely powerful because, as the developer, you can make custom templates for very specifi c situations if needed. This is best illustrated with the fl owchart in Figure 9-3, adapted from the WordPress Codex. There is a more complete version online. c09.indd 233 12/6/12 1:21 AM 234 ❘ CHAPTER 9 THEME DEVELOPMENTVisitor Request is_search() is_front_page() is_page() is_404() is_attachment() is_archive() is_author() is_category() is_tag() tag-{slug}.php front_page.php category-{slug}.php author-{nicename}.php page-{slug}.php {custom}.php tag-{id}.php author-{id}.php category-{id}.php single-post.php attachment.php {mimetype}.php author.php tag.php page-{id}.php single-{posttype}.php category.php search.php home.php pagpe.php 404.php single.php archive.php index.php FIGURE 9-3: The WordPress template hierarchyAs you can see, there is a nice decision tree happening here, and the fl exibility is very powerful. Not all themes have or need all template fi les. But certain more customized or special use case themes can capitalize on this hierarchy and create a unique application of WordPress.It’s also worth mentioning that the search template hierarchy is defi ned in template-loader.php, where a hook is defi ned before the search tree is started — template_redirect — that lets you change the template selection process. This is used mostly for handling URL redirections, like a “shortlink” defi ned for a page, which might hide some of the URL information normally used to decipher what templates WordPress applies.WARNING On some sites we have built, there have been occasions where categories, tags, pages, and even authors have had the same or similar taxonomies. For example, on a corporate news site, you may have a page about a department and a department category for news about that department, and some information may be tagged by the department name. In cases like these, the WordPress template decision tree can get confused and make unintended choices. You can work around this in several ways: either by carefully crafting your taxonomy, by ensuring each slug is suffi ciently unique to avoid collisions, or by enforcing your desired behavior via the .htaccess fi le. The crux of the issue here is how WordPress handles permalinks, which boils down to pattern matching on the slug metadata. c09.indd 234 12/6/12 1:21 AM Creating Your Own Theme: Additional Files ❘ 235CREATING YOUR OWN THEME: ADDITIONAL FILESIt is tough to sort out the various template fi les into which ones are critical, which are essential, and which are just nice to have. Each theme’s template fi le collection will be different and tailored to match the content or design goals of the author. The truly critical and essential templates have already been covered. In some circles, many of the following templates would fall into the categories already discussed, so you will have to make your own decisions here. Do not think that because these templates are being covered later, they are any less important than any other template. Consider each template type a tool, and how you use the tools is what truly matters.Handle 404 Errors: 404.php A 404 page is a fact of life. Eventually, your visitors will fi nd something that went stale. In contrast to a traditional website, WordPress really helps you avoid them because typically all the navigation items are dynamically created by content that actually exists. But it is still possible that your visitor will fi nd a link that is no longer around, so your 404 page comes up. The Twenty Eleven theme provides a really good practice with the stock 404 template by including a search box, recent posts, most used categories, and a tag cloud. This way, visitors who stumble across this page have an opportunity to fi nd what they are looking for. Other good practices include showing a list of possibly related content, in the form of “I couldn’t fi nd what you asked for, but maybe one of these posts would interest you.” You do not want a 404 page to be a dead end; always offer something else to view and a way out. At our shop, we trigger a developer e-mail or Twitter warning to let you know someone asked for a lost URL. Especially if there is a referrer in the HTTP headers, you can track down where the broken link originated. At the least you know something went wrong and can do some research. Also, your 404 page should be funny. Humor is good medicine and it is nice to disarm visitors who might be upset that what they were looking for is not there. It is good practice to expose errors to your developers but show something useful and meaningful to your site visitor. Think back to the days of the Twitter fail whale. As Twitter was growing, it often had scalability issues and the fail whale was seen more often than not. But by keeping the error message lighthearted, the Twitter fail whale has quickly emerged as an Internet icon and garnered its own cult following. Although not strictly a template fi le, another error to hide from your visitors is a database connection error. The default database connection error is ugly and exposes a little too much information to your visitor, who hopefully is a good guy and not going to use that information against your website. WordPress introduced a new function in version 2.5 and later back-ported it to previous versions where, if the database connection fails, WordPress looks for a db-error.php fi le in your wp-content directory.NOTE This fi le resides outside of your theme directory. Because there is no database connection, WordPress does not know what theme to display. c09.indd 235 12/6/12 1:21 AM 236 ❘ CHAPTER 9 THEME DEVELOPMENTYou can put whatever code and CSS in the db-error.php template you want, except dynamic data or WordPress functions, because they will not work without the database. This is another situation where we place a stock db-error.php in all of our WordPress sites, with a generic but friendly error message and then notify the development team that an error has occurred.The following is a sample db-error.php fi le:<?php //error_reporting('E_ERROR'); mail('developers@mysite.com','WP SQL Connection Issue on '.$_SERVER['HTTP_HOST'], 'This is an automated message from the wordpress custom db error message file.'); ?> <html> <head> <title>Temporarily Unavailable

is Temporarily Unavailable

The webmaster has been alerted. Please try again later.

In the rare occurrence that WordPress cannot connect to the MySQL database, rather than showing an ugly database error, site visitors get a friendlier error message and the developers receive an e-mail. This also informs the visitors that no further action is required on their part, besides checking back later, because the error occurred on the web-hosting server and not on their side. This acknowledgment removes confusion or uncertainty on the visitor’s side. The caveat to this is that when things go really wrong, beyond just a hiccup, the developers can get fl ooded with e-mails.
Author.php Earlier, you were grouping historical content by category or tag; you can similarly use the author.php template to group all of an author’s content into one view. In addition, you can create specifi c author
c09.indd 236 12/6/12 1:21 AM Creating Your Own Theme: Additional Files ❘ 237
templates either by the author’s ID or by the author’s nicename, which is the author’s username. As before, the human readable nicename template is preferred by WordPress over the ID-based one. Sometimes your site has multiple authors, such as your development team site at work. In cases like these, a visitor may want to fi nd additional articles posted by the same individual. The author.php template fi le shows only posts written by a specifi c author. The author template behaves just like a category or tag loop. One nice feature of the Twenty Eleven theme is that this template also includes any author information that the author chose to submit in the admin Control Panel.

If the author submitted some biographical data, that information is published here. This functionality could be enhanced if the profi le page had a rich text editor for the biographical information, and possibly some expanded custom fi elds. In production sites, these fi elds have been used to create a multi-business partner site where each author was, in effect, a company. You can also create a Rolodex-type site using this method.
Comments.php The comments template used to be one of the more complex templates. This template fi le handles both the comment loop, including trackbacks and pings, and the input form for a visitor to submit the comment in both logged-in and logged-out cases. Although these tasks are functionally related, sorting through this template fi le, you’ll see a lot of “if . . . else” conditionals that make it diffi cult to theme. Your theme may not even include comments, especially if you are using WordPress as a CMS, but if it does, you can include the comments functionality templates in your other templates with the following code:
Countless variations on the comments theme exist for the look and feel — way too many to discuss the merits of any in particular. One thing to consider when working on this template fi le is the
c09.indd 237 12/6/12 1:21 AM 238 ❘ CHAPTER 9 THEME DEVELOPMENT
threaded comments functionality introduced in WordPress 2.7. See the WordPress Codex for more information about using wp_list_comments(). It should also be noted that in WordPress 2.7, the comments loop was simplifi ed to look more like a traditional post loop in the code. In addition, many new functions have been introduced to make the comment templates much more straightforward, and the Twenty Eleven theme does a great job of utilizing these functions. The Twenty Eleven comment template is a good place to start if you are looking at overhauling the comment section of your site.
One particular improvement is the comment_form() function. This function now handles the rendering of the actual comment form in the comment template. Prior to this function, all of the form and form logic was handled in the template itself, which added extensively to the complexity. This function was introduced in WordPress 3.0 and is pretty extensible if you need to customize your comment form. As mentioned, the comments template can be confusing and is a whole subtheme unto itself because there is so much going on. Some partial theme websites have popped up that simply sell comments themes — for example, http://commentbits.com/. Not a whole site theme, but just the special templates for comments with a few variations. This could be a simple way to get a stylized comment subsystem up and running quickly.
Adding Functionality to Your Templates: Functions.php The functions.php template is not a display template, so it is not like the other templates you have covered, but it is a very important fi le even though it does not directly display content on your website. Chiefl y, the functions.php fi le is where the special sauce that makes your theme tick goes. It is the place where you can put what has traditionally been called “library code.” If in your templates you fi nd repeating code or need some special functionality, this is where it can go. WordPress automatically includes this fi le during execution so the functions are available in all of your template fi les.
Often when you are adding functionality you have to decide if the code belongs in functions.php or in a plugin. A general rule of thumb is that if you are adding something that is confi gurable, as in the user may want to disable it without affecting the look and feel of the site, it belongs in a plugin. If you are including something that is essential to the theme and is always on, it belongs in functions.php.
The stock functions.php theme is very well commented. Each function and logic block of a function has a one-line comment explaining what it does. This makes functions.php easy to modify and extend. However, the majority of these functions will not need to be modifi ed in your production site, unless you have very specifi c needs. Most of them simply add to the template fi les to create a hook-rich HTML template for your CSS styling skills.
One thing that is important to consider when adding on to your theme’s functions.php fi le is whether the functionality you are adding really belongs compartmentalized by theme or whether it is standalone functionality that belongs in a plugin. This is about whether the code you are adding is directly applicable to the theme or if it is portable and can be used no matter what theme the site is running. This can often be a diffi cult choice, especially when you realize that you use the same hooks and fi lters discussed in Chapter 8. In essence, the functions fi le is a library of plugins all nestled into one fi le.
c09.indd 238 12/6/12 1:21 AM Creating Your Own Theme: Additional Files ❘ 239
One of the main purposes of the functions.php fi le is to enable or disable certain WordPress features for your theme. In the Twenty Eleven theme, this is all done during the twentyeleven_ setup() function. You will notice it enables support for various features including post-formats, custom background, post-thumbnails, and a few others. These are all features of WordPress that the Twenty Eleven theme uses; therefore, they must be enabled. Think of this as feature fl ags. How each feature is enabled and confi gured is dependent on the specifi c feature. For example, enabling post- thumbnails or featured images is as simple as this:
// This theme uses Featured Images (also known as post thumbnails) for // per-post/per-page Custom Header images add_theme_support( 'post-thumbnails' );
Some feature fl ags can take, or may require, confi guration information, such as:
// Add support for a variety of post formats add_theme_support( 'post-formats', array( 'aside', 'link', 'gallery', 'status', 'quote', 'image' ) );
However each feature is different and will need to be enabled and confi gured based on your theme’s needs. In addition, the functions fi le establishes and identifi es your navigation menus. In your functions fi le, you introduce how many menus your theme will have and assign them names. Later in this chapter, You will learn how to place menu locations in your template fi les and assign menus to these locations in the WordPress Control Panel.
Similar to menus, you also identify and create widget areas in your functions.php fi le. Generally, widget areas take more confi guration than menus do. Like menus, you register widget areas, or sidebars, in the functions fi le and later in this chapter you will learn how to place these locations in your template fi les. This fi le is for creating your own behavior and functionality for your theme. You could be introducing new presentation logic or new features that are specifi c to your needs and goals. But, also you can override or augment existing WordPress features — for example, in the Twenty Eleven theme:
function twentyeleven_body_classes( $classes ) { if ( function_exists( 'is_multi_author' ) && ! is_multi_author() ) $classes[] = 'single-author'; if ( is_singular() && ! is_home() && ! is_page_template( 'showcase.php' ) && ! is_page_template( 'sidebar-page.php' ) ) $classes[] = 'singular'; return $classes; } add_filter( 'body_class', 'twentyeleven_body_classes' );
This functions adds on to the body_class() function that assigns CSS classes to the body HTML node. The default body_class() function returns many useful classes that you can hook into with your CSS styling, but sometimes you need something special. In the case of the Twenty Eleven theme, the preceding function appends classes to the array that is returned based on certain criteria.
c09.indd 239 12/6/12 1:21 AM 240 ❘ CHAPTER 9 THEME DEVELOPMENT
When modifying the starter theme functions, you have to make a choice. Sometimes, if you are making minimal changes to the fi le, you can just modify the fi le directly, accepting that this will break any upgradeability of the theme. Alternatively, you can include your own custom_functions.php from the functions.php fi le and make all your own custom changes here. The caveat is that if you overwrite the functions.php fi le, either through a theme update or other user error, you have to remember to put the include back in that fi le before your head gets too bloody from beating it against the wall wondering why your custom functions are not running. In practice, both of these scenarios have been used successfully. The amount of power and control available to you in the functions fi le can be staggering and this power can quickly grow your fi le size out of control. For example, some of the more advanced themes and the premium theme frameworks include their own control panels to modify theme settings. These other theme frameworks are covered later in this chapter. Theme control panel code resides in the functions.php fi le. For example, consider the popular Thematic theme framework. To keep things manageable and distinct, the Thematic functions.php is simply a list of includes of other function fi les. This logically breaks up and separates the different facets of the theme framework and keeps the fi les from becoming unwieldy. This theme also includes a basic control panel to control some of the theme settings. To create your own theme control panel, you have to register your theme control panel functions with WordPress. In addition, you have to create the HTML form for your control panel within your functions.php fi le. This is one of the reasons we like the way Thematic has broken up the fi les into separate areas of concern; the mixing of PHP and HTML code never turns out pretty or readable. It is best to keep this information separate and in maintainable fi le sizes. Creating your own theme control panel is outside the scope of this book, but it is defi nitely a great feature to have and most of the premium theme frameworks include this functionality. Having a theme control panel helps your WordPress theme bridge that gap from blogging engine to full- fl edged content management platform for the average user. However, the new Theme Customizer, released in WordPress 3.4 and covered later in this chapter, may work for many sites as a simpler theme control panel. For a coder, WordPress is easily extendible through the code and the vast WordPress functionality, but for the average user, who is probably your client, avoiding code is crucial making these control panels and theme customizers ideal for your end user.
Search.php The search template fi le is really a misnomer. This template is actually the search engine result page (SERP). The search form itself is called searchform.php and is covered in the next section. The concept of a search engine result page is pretty self-explanatory. It is going to show the results of what the visitor looked for, by default in reverse chronological order. Chapter 11 covers some of the weaknesses with the built-in search functionality of WordPress and addresses some alternatives to enhance the user experience. This is all that the basic Twenty Eleven search template does. If there are results, this template presents them to the browser, but if not, it shows a new search form. You can do a couple of things to your search engine result page to improve on the default. First, you do not want your results page to be a dead end if there are not any search results. Plugins are
c09.indd 240 12/6/12 1:21 AM Creating Your Own Theme: Additional Files ❘ 241
available to offer related searches or spelling variation searches based on what was initially entered. This will make the search itself behave more like a traditional search engine. Still, if you do not have any search results, offer up some alternative content that the visitor might be interested in, similar to the way in which the default Twenty Eleven 404 template behaves. This might be a good place for a tag cloud or a list of your most popular content. Plugins are available for showcasing your most popular content or you could create a custom query, but you would have to decide what your metrics are. For some sites, the top content was essentially a known issue — that is, we decided what the top content would be. In this case we created a special post category and made a new loop to show only this category in the SERP page. If you do have results, some people like to see the search terms highlighted in the search engine results page. The Twenty Eleven theme uses the_excerpt() to display the content excerpt in the results. This is where you will make some changes to highlight the search terms. The downside of having your theme split up into many template fi les is that you have to chase the include() and the get_template_part() functions to fi nd the correct fi le to edit. In the case of Twenty Eleven, the get_template_part() is looking for the content template for the proper fi le type. For the sake of brevity, you can chase this back to content.php for general post content. In the content.php template, there is an “if” statement around line 35 checking if the content is being displayed on a search engine results page or not. This is where the theme decides whether it’s showing all of the content or just an excerpt, so you can modify the way excerpts are displayed. Replace this line,
with the following:
\0 ',$excerpt); echo $excerpt; ?>
Because the_excerpt() echoes the content directly to the rendering, you have to use the plugin API function get_the_excerpt(), which returns a string instead. Run this string through the regular expression replace to put span elements around all the search terms and then echo this out to the rendering. In your CSS, you can add a nice rule to highlight these span elements to match your theme. Finally, if your visitors did not fi nd what they were looking for after reviewing the search results, rather than forcing them to scroll back up to the top, you can provide a second search form at the bottom to refi ne their search. After the results loop, add something like the following:
Not seeing what you're looking for? Try again

c09.indd 241 12/6/12 1:21 AM 242 ❘ CHAPTER 9 THEME DEVELOPMENT
The Twenty Eleven theme has the search form already enabled for you. Chapter 12 discusses improving the way search works through plugins and some alternatives.
SearchForm.php The generic search form is pulled from the WordPress core template fi les and is pretty basic looking. In cases where your theme needs a customized search input fi eld, create a new template named searchform.php. This form can then be styled to match the rest of your theme. The search widget automatically uses this template to include this form in your regular templates with the following code:
The basic Twenty Eleven search form looks like this:

Note that because this same form could be used in the unordered lists of the sidebar as well as wherever else you may include it, the HTML markup may need to be adjusted to be generic. Another option is for special-case search forms, often seen in the nameplates of sites, is to create a traditional PHP include for the search form. Make sure the fi lename is not one of the reserved fi lenames for the template engine, and then include it in the appropriate place in your other template:
Remember to use the bloginfo[] array to keep the theme portable. You can also use this method to comply with the DRY principle when there are consistent elements across multiple pages but outside of the header and footer templates. WordPress itself does an excellent job of enforcing DRY through the variety of page templates, assuming you, as a developer, stick to the rules. But there are always more ways to skin a cat and traditional PHP operations can help out here. This functionality is often used to keep the template sizes manageable.
Other Files Here are some other fi les that polish off your theme. For the Manage Themes Control Panel, you will want to include a screenshot for easy visual recognition of your theme. Create an image fi le to represent your theme that is 300px wide by 225px tall and save it as a PNG. GIF and JPG are also accepted and preferred in that order. Traditionally, this image is an actual screenshot of your site using your theme. The remainder of the information for each theme on the Manage Themes page comes from your style.css header information.
c09.indd 242 12/6/12 1:21 AM Custom Page Templates ❘ 243
Many themes include several language fi les and are ready out of the box for localization. If you intend to launch your site in multiple languages, pay attention to the special considerations involved. Localization and internationalization are well outside the scope of this book. Just bear in mind that the WordPress supports this functionality when you need it.
CUSTOM PAGE TEMPLATES
Occasionally, you will have a specifi c page that requires a unique layout, relative to the rest of your website. This could be a contact page, or it could be that each product on a brochure website has its own specifi c page. It could be that you are making a custom landing page for a marketing campaign or a QR code. Maybe using a general page.php template is not going to meet the needs of your site because each page has its own distinctive qualities. Possibly, you have widgets you would like to display on certain pages and not others, although you could probably accomplish this with a plugin like Widget Logic. Or perhaps you are integrating a third-party web application into your WordPress site. This is where page templates step in. You can assign page templates to a page using the Write panel in the Administration Control Panel. WordPress will assign which page template to use when displaying your content following the already established specifi city pattern. For example, if your page is assigned a page template, that will be selected because a page template is the most specifi c option. If the default page template is set, the traditional page.php template discussed earlier will be used to render your content. Finally, if neither of those templates is available, WordPress will use your index.php template. In Figure 9-4, you can see several page templates to choose from, including the default page template, Twenty Eleven’s templates for a showcase page and sidebar page, discussed later, and the two added as FIGURE 9-4: Selecting the examples, Boring and Fancy. page template
When to Use Custom Page Templates Many reasons exist for having custom page templates in your site. Custom page templates are very powerful tools to add to your arsenal, and when used effectively they can extend the breadth of your site immensely. Custom page templates are yet another way to assign templates to specifi c pages. Unlike previous examples, which relied on an inherent attribute of a page, such as the page slug or ID, category, or tag, custom page templates can be assigned arbitrarily through the Write Panel to any page in your site. A simple example is to create page templates for unique product pages, where the sidebar of each product page has unique data and links specifi c to that product. As with everything in WordPress, there are many ways to achieve this functionality, but sometimes all that’s needed when creating custom page templates is a simple, straightforward method. And often, simplest is best. Another simple example is to create a custom page template that uses an iFrame HTML element to include a third-party web application. Depending on the exact needs and aspirations of the site (not to mention budget), this can be a quick and dirty way to integrate two sites into one. The caveats to
c09.indd 243 12/6/12 1:21 AM 244 ❘ CHAPTER 9 THEME DEVELOPMENT
this method are the same as you would usually fi nd when using iFrames, which are bookmarking and competing look and feels. But admittedly, this method has been used before because sometimes the quick and dirty method is all that you need. More complex examples include integrating different web applications into your WordPress site. For example, a page template could be used to create a custom order page that posts directly back into your e-commerce package. This would be a nightmare to set up and maintain inside the WordPress Control Panel, but when using custom page templates, it is all in the code, and you still get the gooey goodness of WordPress to wrap it all in. In real life, custom page templates are used for event calendaring and registration. On one occasion, an expansive education class was built offering web applications for searching and displaying courses as well as registering for attendance either in person or via the web. This system had been in place for several years and was heavily used. The simplest way to integrate this education registration system into WordPress client sites was to create custom page templates. In essence, this extended the existing registration system with some REST web service commands. Then a set of custom page templates was created that communicated with the web services but displayed the contents locally inside the WordPress site wrapper, using the local style sheet. Although setting up the page templates was daunting at fi rst, the benefi ts in the end were enormous: ➤ Continued use of the existing system that corporate staff was already knowledgeable about and trained to use. ➤ Extended registration options to multiple sites, therefore increasing the potential audience. ➤ Even though the registrations were spread across multiple web properties, they were still centralized into the one system. ➤ The education system matched the look and feel of the local website because it utilized the local theme of the WordPress site. How to Use Custom Page Templates Creating the custom page templates themselves is really easy. The goal of the templates and making the templates achieve the goals is what really complicates the matter. To create a page template, copy an existing template that is similar to the new template you are going to make; usually this is the page.php template. Name this new template fi le whatever you want and keep it in your theme directory. However, in our development shops, we tend to follow a convention that page templates are named t_templatename.php. That is, they are prefi xed with thet_ so it is easy to distinguish between traditional template fi les and individual page templates, although the name of this fi le really does not matter as long as you avoid the reserved fi lenames in the hierarchy. To make your new template a page template, you must include a special comment section at the top of the fi le:
c09.indd 244 12/6/12 1:21 AM Custom Page Templates ❘ 245
This must be in the fi rst couple of lines of your fi le for WordPress to scan and register as a page template. In practice, the only thing above this stanza is the source code control comment. The name of your template can be anything you want. It should be meaningful, but not too long, because WordPress will use this PHP comment to populate the drop-down box in the Control Panel. Your page template is now registered with WordPress. The remainder of your page template can be whatever you need to accomplish your page template goals. You can, and most likely should, use the built-in WordPress functions such as get_header() and get_footer() as well as the content gatherers. Basically you can do whatever you need to do here; just remember you will have to sleep in the bed that you make. For example, if you remove the dynamic WordPress sidebar generation and replace it with static HTML, you have also removed all the functionality from the Control Panel to manage widgets on this page template. It would be a better practice to register a new widget area on this page template and continue to use the Control Panel to manage this content. Keep in mind that page templates are not restricted to displaying page information. You could create a page template that displays a traditional post loop or do something that is completely unrelated to the WordPress content. Then just leave the page text editor blank, or use it to write instruction notes to yourself.
Stock Twenty Eleven Page Templates The Twenty Eleven theme comes standard with two page templates for use on your site. You will look at those briefl y here, since you have them available.
The fi rst page template that comes with the Twenty Eleven theme is sidebar-page.php. This template is pretty simple and straightforward. Basically, it adds a sidebar to your page template. Pretty self-explanatory.
The second custom page template is more complicated. It is called showcase.php. The showcase page template is designed to be a fancier index page for your WordPress site. It has a couple of features built in. First, it has a highlighted content area. This content area appears directly below the navigation on Twenty Eleven. This content comes directly from the content of the page that you assigned this template to. Second, it has a showcase for posts. This is similar to what was done earlier in this chapter for the slides and slideshows, but for Twenty Eleven, it uses actual post content. To feature posts, you need to set them as sticky posts. The nice thing about this method is the features can be mixed format, you can have images, text, or images and text in the featured area. Once you have this page published, set it as your front page in the Reading Settings Control Panel and you will have a fancy new index page. Custom page templates are very powerful tools. Truly, if you cannot fi t your content into the predefi ned template types, you always have this last trick up your sleeve to make a custom page template and override everything. This is also a great way to add special non-WordPress functionality to your website.
c09.indd 245 12/6/12 1:21 AM 246 ❘ CHAPTER 9 THEME DEVELOPMENT
OTHER THEME ENHANCEMENTS
These are some additional enhancements that you can make to your theme. Most of the following ends up in your functions fi le and not as individual fi les. These are enhancements to your theme that enrich the site administrator’s CMS capabilities.
Menu Management As mentioned before, most WordPress sites that are being used as CMS capacity have a mixed bag of pages and posts. The most diffi cult part of the hybrid pages and posts layout is creating a meaningful navigation. Your site’s global navigation is a very important aspect of your site if you intend to have any stickiness with your visitors. Visitors should be able to explore your content organically and experimentally through related posts and pages, but there should also be a strategy to your content organization and this is the function of your global navigation. On occasion, we have lucked out on the structure of a site and have been able to create two tiers of navigation, one for the page content and one for the post content. Before WordPress 3.0, the two content types essentially needed to be intertwined and the navigation had to be hand-coded using the wp_list_pages() functions with many different parameters to get the menus you wanted. This was all coded in the templates and not very fl exible for the site administrator. However, those days are gone. With WordPress 3.0, a new Menu Management system has been introduced. This menu management gives all the control to the site administrator. As a theme developer, you just have to set it up for your theme presentation.
First, in your functions.php template, you must enable the menu feature. This is done with:
if (function_exists('add_theme_support')) { add_theme_support('menus'); }
The next step is to register the menus for your theme. Basically this means assigning named locations for each menu to earmark the HTML real estate for the menu. You will use the register_nav_menu() function for this. This function takes two parameters. The fi rst one is a nickname or handle that you will use in the template fi les. The second parameter is a friendly human-readable name that is used in the WordPress Control Panel. For example, the following will create a single global navigation menu for use in your theme:
register_nav_menu('primary', 'Global navigation menu');
You can actually have as many menu locations in your theme as you want or need. Just feed the register_nav_menu() function an array of locations, like so:
register_nav_menus( array( 'primary' => __( 'Primary Navigation', 'twentyten' ), 'supernav' => __( 'Super Navigation', 'twentyten' ), ) );
This will notify WordPress that you have menu locations available and identifi ed, but you also need to assign their position in the template fi les. Usually, because of the way websites are designed, this
c09.indd 246 12/6/12 1:21 AM Other Theme Enhancements ❘ 247
occurs in your header.php template. To place the desired menu in your template fi le use the wp_nav_menu() function like so:
'primary' ) ); ?>
This function can take many parameters, passed in as an array, to control the HTML styling, but the important parameter is to identify which menu you want placed at this location. In the preceding example, the real estate is allocated for the menu nicknamed primary. Finally, to glue this all together, your site administrator can use the Menus Control Panel to manage the menu. Notice you are identifying a menu location, and then assigning that location to an actual position in the HTML hierarchy. This is all at the code level. In turn, the site administrator assigns content to these named locations through the Control Panel. So while they all must be set up together so that they work together, they are actually disconnected. Assigning meaningful names to the menu locations is important for the Control Panel aspect of menu management, but how the site administrator uses that menu may be different than you intend. What is meant by “disconnected”? Let’s go back in time to how WordPress used to build menus before the new menu system. This process involved using the wp_list_pages() function with many parameters to hand-craft the exact menu you needed. In fact, the fi rst edition of this book devoted many pages to reviewing this topic. Creating the menus programmatically in the template fi le worked because it was directly tied to actual content of the site and the hierarchy of pages. However, it was not perfect. You had to use tricks such as building a blank page to show up in the automated navigation menu, and then use the Page Links To plugin by Mark Jaquith to redirect that page to category or archive templates. In addition, the PageMash plugin was recommended to manage the page hierarchy and page order for the wp_list_pages() function. This tried and true method is frequently employed for many sites. It works because it is programmatic, meaning it is predictable. It works because it is directly tied to content. It sometimes does not work when the content gets a major change.
Sometimes, a change in the content means the wp_list_pages() parameters need to be adjusted. With this method, the changes have to be made at the code level, and the power is taken away from the site administrator. Whether this is good or bad is a choice you have to make based on the convenience and needs of your site. The predictability of the new menu management system is another problem. With the menu system, your site navigation is arbitrary. It’s not directly tied to your content. You can automatically add top-level pages to a menu, but you cannot automatically add the child pages. In addition, the page hierarchy isn’t refl ected in the menu system. You have to manually manage the menu above and beyond the management of content. One possible trap is that when you delete a page from your site, the menu item remains. This disconnect can be both a pro and a con. On the one hand, the site administrator really has complete control over the menu content. He can hand-craft the menu to meet his needs. However, it is important for your site administrator to understand that he has to manage the content and the menu. There can be confusion when some aspects of the site navigation are programmatically created in the theme templates, but the menu is handmade.
c09.indd 247 12/6/12 1:21 AM 248 ❘ CHAPTER 9 THEME DEVELOPMENT
For example, imagine you have built a new theme for a client that has multiple product pages. These are special pages to highlight individual products with their specifi c information and details. To further enhance the user experience, and perhaps cross-sell some product, you have built a custom page template for the products pages that has a built-in related products section at the bottom. This related products section is generated by code in the imaginary t_product_page.php custom page template. The challenge is that when a site administrator adds a new product page, it will show up automatically in this related product page code on some other sites, but will not show up automatically in the menu. The site administrator will have to manually edit the menu to add this page. This is not a devastating issue; it’s just disconnected and an extra step. The challenge is in empowering the site administrator and asking him or her to manually confi gure things, versus simply adding code to have things happen automatically.
Widget Areas Widget areas work very much the same way as menus. In your functions.php fi le, you identify and name different areas for different parts of the site. These are often thought of as sidebars but can be so much more. Do not restrict yourself to thinking widget areas only belong in the sidebars of your site. Many themes, including Twenty Eleven, are expanding the number and location of widget areas to include the nameplate or header area, the footer, and even the middle of the loop. You have seen themes that have hundreds of widget areas. The nice thing about widget areas is their fl exibility. The number of widgets that can be placed into a widget area is immense. Having multiple widget areas empowers the site administrator to control content in areas of the site that are really outside the primary content areas of the site. As previously mentioned, setting up widget areas is very similar to setting up menus. In your functions.php fi le, you must identify and name your locations. Because widget areas have more fl exible and varied content than menus, which are pretty much unordered lists, you generally pass some HTML wrapper information for use when rendering the widgets. Also, because widget areas have evolved from the traditional sidebar use, the function to register them is still named register_sidebar(), but again, don’t let this pigeonhole them. Here is a widget area code snippet from Twenty Eleven:
register_sidebar( array( 'name' => __( 'Main Sidebar', 'twentyeleven' ), 'id' => 'sidebar-1', 'before_widget' => '
', 'after_widget' => "
", 'before_title' => '
', 'after_title' => '
', ) );
Similar to menus, you pass the function a friendly name for use in the Control Panels and an identifi er for use in the theme templates. Beyond that, the additional parameters are for styling the widget consistently. In this example, Twenty Eleven is using HTML5 aside elements to wrap each widget and widget titles in h3 tags. This code notifi es WordPress that there is a widget area available for content.
c09.indd 248 12/6/12 1:21 AM Other Theme Enhancements ❘ 249
The next step is to assign the HTML real estate position to this widget area. For this example, you will look at sidebar.php in Twenty Eleven, but again, widget areas can be anywhere in your template. Here’s the code:

'monthly' ) ); ?>

A couple of things are going on in this code snippet. First and foremost, the fi rst line is looking to see if the widget area named sidebar-1 has content assigned in the Control Panel, and if it does, it will display it. This is one of the big benefi ts of widget areas: if they do not have content, they do not display unless you follow the paradigm outlined in the preceding code. In this case, if the widget area does not have widgets assigned to it, then the default content will display. In the preceding example, if no dynamic content was set up in the Control Panel, this widget area will show the archives and the meta widgets automatically. How you set this up depends on your needs. You can just as easily provide widget areas with no default content to expand the possibilities of your theme.
Post Formats This is simply a feature fl ag that you can turn on or off in your functions.php fi le. If your theme intends to use the built-in post formats, or a subset of them, you can enable them. Post formats are essentially a way to customize the display of certain types of posts. This is most commonly seen when you are using WordPress for blogging or archiving a journal. The different post formats can be used to pull different loop HTML rendering as you saw earlier in this chapter. This allows you to present quotes or links differently than full posts. WordPress currently supports ten post formats for varying content. You can enable any or all of these formats depending on the goals of your theme. The standard format is for traditional posts and is enabled automatically. This is the format used in WordPress forever; it just now has a name assigned to it.
c09.indd 249 12/6/12 1:21 AM 250 ❘ CHAPTER 9 THEME DEVELOPMENT
In addition, there are nine new formats as of WordPress 3.1. Here they are, with the recommended styling, although using the fl exibility of WordPress, you can style these to fi t your needs: ➤ Aside — This is similar to a quick note. It is usually presented without the post title. ➤ Audio — Obviously, this format is for an audio fi le, perhaps a podcast or a band releasing a single. ➤ Chat — This format is usually a chat transcript. This is usually styled using the pre HTML element to keep the line breaks. ➤ Gallery — This is a gallery of image media attachments. The actual post content will typically contain a gallery shortcode. This format is for styling the gallery. ➤ Image — This post format is for a single image. The single image can be embedded in the post content, or a URL in the post content will pull that image to your site. ➤ Link — This format is for a link to another URL. Generally, these are presented as simply the link, without the title. This format is often used for creating your own bookmark site or reminders about URLs that interested you. ➤ Quote — Another self-explanatory one — this format is for quotes. This format is used to archive quotes that have some special meaning to you. You can present this format without the title or fl ip it around and use the title information as the attribution to the quote. ➤ Status — Think of this format as Twitter or Facebook updates. Typically presented without a title. You can use this format to make your own Twitter clone. ➤ Video — Similar to image and audio, this format is for presenting a single video to your visitors. The video can be embedded in the content or as an external URL. To enable post formats for your theme, simply select which formats you intend to use and pass them as a parameter array. For example, the Twenty Eleven theme is supporting a subset of the previous formats:
add_theme_support( 'post-formats', array( 'aside', 'link', 'gallery', 'status', 'quote', 'image' ) );
Remember that the standard post format for traditional post content is always enabled. Post formats can tailor your theme to specifi c niche uses or broaden your theme to present different content types in unique and customized ways.
Theme Settings Many of the theme frameworks offer a special Theme Settings Control Panel for customizing the theme framework. This is a coded solution that comes from the theme developer but creates a new Control Panel with whatever settings the theme developer has opted to include. This is yet another feature that is a balance of empowering the site administrator as opposed to handling aspects in the theme template code. Creating your own Theme Settings Control Panel is a pretty complex endeavor that is outside the scope of this book. Each theme is different, and it’s the developer’s goals that determine which features or aspects of your theme are confi gurable.
c09.indd 250 12/6/12 1:21 AM Theme Hierarchy and Child Themes ❘ 251
To create a Theme Settings Control Panel, you fi rst have to build the control panel code and forms and register them with WordPress. You then have to take the confi gurable options and use them in your template fi les. The control you give to your site administrator can be very powerful, but it does make developing your templates a little trickier. For more information about creating your own Theme Settings Control Panel, check out the WordPress Codex and other theme frameworks; there are also many good tutorials online.
Theme Customizer Some of the functionality of Theme Control Panel has been moved into the new Theme Customizer, which was introduced in WordPress 3.4. This is a new Control Panel for customizing the theme. The really neat thing is that it can show the site administrator a live preview of the site while he is customizing it. This is truly the biggest benefi t of this component. This real-time live preview allows the site administrator to experiment with the site and see how it would look without affecting the live production site until he is done. In the past, this process involved making a change in a Theme Settings Control Panel, discussed previously, in the code, or in other customizable places, and publishing those changes to the live site. Then the site administrator had to browse to the live site to see the outcome. At the same time, any visitors browsing the site saw the in-process design changes. The change may or may not have been what the site administrator intended, or worse, may have broken some display aspect. The live preview presents this whole process while allowing great control. The Twenty Eleven theme is the fi rst theme that is using this new set of functions to any great extent, although it is expected that many more themes will be using it by the time this book is published. Basically, the Theme Customizer uses the WordPress settings API to store confi gurable design information. Then using specially crafted functions in the functions.php fi le, WordPress applies the changes to the HTML.
In the Twenty Eleven function for changing the header color, the functions.php fi le injects a new CSS stanza into the HTML head that overrides the style sheet. In practice, this is not really optimal code for a high-traffi c site; however, this is yet another example of trading optimization for site administrator confi gurability.
THEME HIERARCHY AND CHILD THEMES
So far in this chapter, you have looked through the template fi les that make up a complete theme, focusing on the stock Twenty Eleven theme. You even considered renaming it and making your custom theme in that new directory using the Twenty Eleven theme as a starter theme. This is a good way to get started with theme creation as it helps you dive into the internals of how a theme works. And, in the real world, this is how many development teams work today. This method works well because you know exactly where your template fi les and CSS fi les are that need to be edited. The whole theme is self-contained, which minimizes workfl ow and deployment efforts — not that it’s perfect, but it is very solid. However, with the release of WordPress 2.7, child themes became a functional reality. While you could implement child themes prior to WordPress 2.7, it was not until template fi le inheritance
c09.indd 251 12/6/12 1:21 AM 252 ❘ CHAPTER 9 THEME DEVELOPMENT
was included that child themes became a viable development option. Child themes let you take an existing theme or theme framework and use the best parts of it, and then extend and modify it, license permitting, to meet your own theme’s needs while maintaining future updates to the parent theme. After you have the basics of theme development down, it is highly recommend that you pick a theme framework you are comfortable with (a few are mentioned in the next section) and create child themes. Child themes are the future of theme development for WordPress. This concept is pretty revolutionary for several reasons. First, it certainly opens the door for theme frameworks. Starting with a solid foundation, you can now make countless variations on the theme simply through inheritance. Theme frameworks tend to be very plain, and intentionally so, but by using child themes, you can inherit all the CSS semantic hooks and microformat gooey centers and build your own candy shell around it, basically taking the best parts and making a new creation. Second, updates to the parent theme or theme framework will not overwrite your customizations. Previously, when you made modifi cations to your copy of the theme, you had to keep track of the changes you made so that you could reapply them when the theme was upgraded. This can be somewhat automated via a source code management solution, but it is arduous at best, when it works. And there is always the day when you forget to make a modifi cation to the updated fi les. Third, child themes led the way for auto-updating themes in the Theme Manager. Occasionally theme templates are vulnerable to security exploits such as cross-site scripting. Using a properly inherited child theme means the parent theme can auto-update to address security issues while not affecting your child theme. This creates a more secure implementation for your site. There are a couple of caveats here. The functionality that keeps your child theme customizations unaffected works both ways. If you override a particular template fi le with your own customizations, any enhancements to the parent template fi le of the same name will not cascade to your unique fi le. In practice, this could create a false sense of security, where you may have copied a poorly coded template fi le to modify, and then changes were made to the parent version but your fi le is unaffected and still vulnerable. That is, because you are carrying forward the vulnerability in your extended code, you continue to override any repaired code. This would not only apply to security amendments but would also apply to any feature enhancements. That is, child themes do not totally remove you from the code management process. In addition, there is a little bit of CSS overhead here. Generally, a child theme builds upon the CSS of the parent theme. And, in truth, that is exactly how CSS is designed to work, hence the word cascading in the name. So, for this to work in child themes, the child theme has to include the CSS from the parent theme, even the rules that get overridden in the child theme. That means that the byte weight of the CSS in your child theme may be quite a bit larger than what you actually use in the browser, but you have to transfer it all anyway. That said, child themes are a fantastic feature of WordPress, and we recommend using this methodology when the situation warrants it. Certainly maintaining a pristine theme framework and then extending that theme to individual sites adds to the benefi ts of a common theme vernacular of CSS and functions, as well as the other benefi ts mentioned previously. Again, using child themes is the future for WordPress theme development and is the best practices recommendation. Take a look at how child themes actually operate and what is required in making your fi rst child theme. The fi rst thing you need to do is fi nd the theme you are using as the parent. Your parent
c09.indd 252 12/6/12 1:21 AM Theme Hierarchy and Child Themes ❘ 253
theme does not have to be labeled a theme framework. You can extend any theme as long as it meets the following conditions: ➤ The licensing permits you to extend or modify the theme. ➤ The parent theme is not a child theme itself. In this example, you will continue to build on the stock Twenty Eleven theme, but you could use any theme or theme framework as the parent. As alluded to earlier in the chapter, to make your custom theme a child theme of another theme, you must add a line to the header information of your style.css fi le. This line informs WordPress of the location of the parent theme. Therefore, the variable in the comment should be the folder name of the theme. Although it depends on the server, is best to be case-sensitive when naming your theme. In this instance, you are adding the following line:
Template: twentyeleven
To illustrate this, the entire header comment block from the sample child theme reads as follows:
/* Theme Name: A Twenty Eleven Child Theme Theme URI: mirmillo.com Description: A sample child theme Author: David Damstra Author URI: mirmillo.com Template: twentyeleven Version: 1.0 */
As discussed previously, having the style.css fi le with the properly formatted header information in your uniquely named folder registers your theme with WordPress. The next step is to import the CSS from the parent theme so that your custom theme has base rules to work with:
/* import the base styles */ @import url('../twentyeleven/style.css');
At this point, you can activate your theme in the WordPress appearance Control Panel. You have a fully functional child theme of the Twenty Eleven theme. It will look exactly like the Twenty Eleven theme because it is, in essence, a practical copy of the parent theme. The remainder of your style sheet operates like traditional CSS where you can override previous rules through the CSS rules of specifi city and precedence, including the order in which they are listed — because your custom styles appear later, they will take precedence. Again, working with CSS is outside the scope of this book, so let’s, go ahead and extend the child theme a little bit. Although you can make these same changes with the Theme Customizer presented earlier, for the sake of this example make the changes in CSS. Update the child theme with a nice pink background and change the base font. Here’s what the complete style.css fi le might look like:
/* Theme Name: A Twenty Eleven Child Theme Theme URI: mirmillo.com
c09.indd 253 12/6/12 1:21 AM 254 ❘ CHAPTER 9 THEME DEVELOPMENT
Description: A sample child theme Author: David Damstra Author URI: mirmillo.com Template: twentyeleven Version: 1.0 */
/* import the base styles */ @import url('../twentyeleven/style.css');
body { background: #E0A3BD; color: #333; font: 100%/1.5 calibri, arial, verdana, sans-serif; }
From here on out your browser developer tool is your best friend. Use the inspector to see the current style rules applied to various elements and make the appropriate changes in your child theme’s CSS fi le. Again, remember to follow the precedence and specifi city rules of CSS. Your child theme can be as simple or complex as you make it. You can create a completely unique theme by simply editing the style sheet, as you have done previously. Or your child theme can turn into a completely new theme with all new templates, although this most likely defeats the purpose of using a child at all. Here is how it works. When WordPress makes a decision on which template fi le to use, fi rst it scans your child theme directory for that fi le. If that fi le does not exist, the parent theme directory is scanned. WordPress will prefer your template fi les over those of the parent theme, which means you can override the functionality of specifi c templates while maintaining the core of the parent theme. Or, your child theme could introduce custom page templates, but the foundation templates are pulled from the parent. There is a wide scope of opportunities here, although keep in mind the previously mentioned limitations. The easiest way to accomplish this is to copy the template fi le you want to modify from the parent theme directory into your child theme directory and then modify as needed. For example, the author template in the Twenty Eleven theme is perfectly functional, but suppose you want to change the size of the author image in this template. Again, this is an intentionally simple example and there are many ways to copy this.
First, copy the author.php template from the Twenty Eleven theme into your child theme directory. Second, edit your child copy to change the avatar image size around line 46 of the code. It might read something like this:
In this example, you doubled the size of the image from 60 pixels wide to 120 pixels wide. You can see an example of what this looks like in Figure 9-5.
c09.indd 254 12/6/12 1:21 AM Theme Hierarchy and Child Themes ❘ 255
FIGURE 9-5: Child themes make it easy to apply styles to specifi c pages.
You can further extend the child theme with your own functions.php fi le. WordPress automatically includes the parent theme’s functions, but in addition, it also includes your child theme functions. You do have to be conscientious about function naming. Be very careful not to create functions in your own theme that have the same name as a parent theme function. If you need to override functionality, the authors’ advice is to make a new function in your own theme with a new name to avoid name resolution confl icts and adjust the template fi les as necessary to call your function instead. In addition, theme frameworks have advanced signifi cantly and many include multitudes of custom hook locations and fi lters for you to capitalize on. Using these custom hooks and fi lters, you can actually use your child theme’s functions.php to inject and modify the parent theme’s HTML without making a second copy of the template fi les. This is a process that builds on the topics covered in Chapter 8. This is a much more complex way to build child themes but provides you the most safety because you are able to update the parent theme in the future as your child theme uses the hooks of the parent to amend and change the theme to make it your own. As you can see, child themes are yet another powerful tool in the WordPress theme arsenal. You can quickly get a theme up and running using an established theme as a base, and then modify and extend only what is required to create your own theme, all the while future proofi ng the upgradeability of your foundation theme. This really is a game changing feature once you grasp it. It’s not a simple concept, especially when you use a framework with custom hooks and fi lters. Even if your design team hand-codes
c09.indd 255 12/6/12 1:21 AM 256 ❘ CHAPTER 9 THEME DEVELOPMENT
each theme from scratch, having a foundation to start from offers a number of benefi ts, including increasing effi ciencies because commonly implemented features are already being implemented consistently, and they also have the familiar CSS and markup vocabulary that your team is intimately familiar with. Regardless of whether your parent theme is one of the popular theme frameworks or something you have developed in-house, the benefi ts are quite tangible.
PREMIUM THEMES AND OTHER THEME FRAMEWORKS
Thus far in this chapter, you have explored the Twenty Eleven theme and used it in most of the examples. But certainly, it is not the only theme or theme framework out there and may not be the best match for you or your development team. Many of these other themes you will look at briefl y include another layer of abstraction in them or a fl urry of functions in thefunctions.php fi le. Generally, this abstraction brings the ability to modify the theme into the WordPress Control Panel. This may be ideal for certain clients who are not PHP- savvy and want that control delegated to the site administrator rather than the developers. The best way to make a choice here is to try each theme out and kick the tires. Find a theme or theme framework that fi ts your coding style and needs and then run with it. Remember that you can make child themes or modify themes to meet your needs (license permitting, of course) from basically any theme out there, but with the new child theme functionality in WordPress 2.7, there has been a growth spurt in theme frameworks. You take a cursory look at some of the more popular theme frameworks (at the time of this writing) here. Many are out there, so be sure to look around. Please keep in mind that various terms are thrown about with regard to themes. Magazine themes and premium themes mean different things to different people. Sometimes premium means the theme costs money; other times it means it includes an administration control panel. Some themes that are available for a fee are called commercial themes. A theme framework is typically developed to be built upon. Although they may stand by themselves, they are intentionally written for extension. Starter themes are meant to be forked and edited in place. Your needs may vary with every project, and certainly you need to fi nd a theme that speaks to you. The following is just a sampling of some more popular themes that we have used in the past. There are many more to choose from and we are not endorsing any one over another.
Bones Theme Bones is a starter theme by Eddie Machado. The Bones theme is built on top of HTML5 boilerplate as a foundation, meaning that it is pretty forward thinking. We like Eddie’s philosophy that child themes and theme frameworks are great, but sometimes they make things more complicated than they need to be. The simplicity of taking a starter theme and making a one-off project theme for a site appeals to many seasoned developers and this is the goal of the Bones theme. In addition to HTML5, the Bones theme is a responsive base using media queries and a mobile-fi rst mentality. Responsive web design is covered a little more in Chapter 12, but know that if you are making sites that you expect to be viewed on smartphones, having responsive views from the get-go helps. Bones also includes LESS and Sass CSS functionality for advanced developers. Check out the Bones theme at http://themble.com/bones.
c09.indd 256 12/6/12 1:21 AM Premium Themes and Other Theme Frameworks ❘ 257
Carrington Theme Carrington is a theme framework by Alex King’s Crowd Favorite. Carrington is designed for child themes and is built to be very modular, meaning you add in what functionality you need. Carrington does this by abstracting code into small components. This allows code reusability and keeps things organized. At fi rst glance, Carrington can seem complicated, but once you digest the processes involved, it makes sense. Crowd Favorite also has some other interesting WordPress projects, including RAMP, which was mentioned in Chapter 3, and the Carrington Build theme, which is a drag-and-drop pay layout generator. Learn more about the Carrington theme at http://carringtontheme.com.
Genesis Theme The Genesis theme framework by Brian Gardner’s StudioPress is one of the most, if not the most, popular theme frameworks around. The Genesis theme framework is designed exclusively for child themes, and StudioPress even sells many variations. To this end, the Genesis framework has many additional hooks and fi lters for customizing your child theme to make it unique. The Genesis theme framework is an evolution of the Revolution theme. The Revolution theme was a pioneer in WordPress themes and really raised the bar to change theme development standards. Revolution was one of the fi rst themes to embrace the magazine theme style that helped WordPress transcend the blog stereotype and become a viable CMS solution. Magazine-style themes made WordPress look less bloggy and more like a traditional website. In addition, the Revolution theme was one of the early commercial themes. The Revolution theme has since been retired and is no longer available. However StudioPress has taken its experience and created Genesis and many child themes.
You can fi nd the Genesis Theme online at http://studiopress.com.
Hybrid Core Theme The Hybrid theme by Justin Tadlock is free, but charges a club membership fee for access to the theme documentation, tutorials, and support forums. This theme includes a nice control panel to toggle various features and CSS hooks on and off. The Hybrid theme has several ready-made child themes available. This theme has rich CSS hooks throughout the posts and body tags. It also includes numerous widget- ready areas and many custom page templates in the stock installation. These custom page templates cover a variety of use cases and really add to the theme, if you know how to use them. The Hybrid Core theme is modular with many features and extensions that can be enabled if you need them.
You can fi nd more information about the Hybrid Core theme at http://themehybrid.com/.
Roots The Roots theme, developed by Ben Word, is another starter theme. Like Bones, this theme is based on HTML5 boilerplate and also Twitter Bootstrap. Because this theme is based on Twitter Bootstrap, it is also a responsive theme for mobile devices.
c09.indd 257 12/6/12 1:21 AM 258 ❘ CHAPTER 9 THEME DEVELOPMENT
One of the interesting features of the Roots theme is the included .htaccess fi le for use on Apache web servers. The .htaccess cleans up URLs throughout your site by redirecting some of the WordPress recognizable paths for images, CSS, JavaScript, and plugins to be more traditional URL paths. In addition, the .htaccess rewrites the search URLs to be more human-readable and makes most asset URLs root relative. All in all, this theme does a good job of further cleaning up WordPress URLs and making them more semantic.
The Roots theme is available online at http://www.rootstheme.com/.
StartBox Theme StartBox is a theme framework developed by Brian Richards for building child themes. Like the Hybrid theme, the framework itself is free, but there is a club membership fee for access to the child themes, tutorials, and support. The StartBox theme includes an extendable Theme Options Control Panel and many built-in shortcodes for commonly requested tasks such as call-to-action buttons and social media links. An interesting feature of the StartBox theme is the sidebar manager, which allows the site administrator to create widget areas through the Control Panel. The StartBox theme, like many of these other themes, has the venerable Sandbox theme as an ancestor, meaning it has many CSS hooks built in throughout the HTML.
Learn more about the StartBox theme online at http://wpstartbox.com/.
Thematic Theme Thematic is a theme framework developed by Ian Stewart. The Thematic theme is free with a decent breadth of existing child themes available. Child themes are available both free and commercial. Thematic also includes a minimal administration control panel to modify limited information. Two features really stand out. First, this theme’s ancestry includes the Sandbox theme. The rich semantic CSS hooks that are found in Sandbox have been brought into Thematic and extended. Second, this theme includes 13 widget-ready areas. Thematic includes many search engine optimization and layout features. You can fi nd more information about the Thematic theme at http://themeshaper.com/thematic/.
SUMMARY
In this chapter, you covered how to use themes to organize, structure, and present your content. Your theme is the face of your site, and no matter how good your content is, this presentation is what really seals the deal on the user experience. A theme that looks amateurish can hurt the credibility of your site, whereas a sharp, professional theme can enhance the whole experience. In the next chapter, you will look at taking external content sources and incorporating them into your WordPress site to further develop the quality of your content and the user experience.
c09.indd 258 12/6/12 1:21 AM 10 Multisite
WHAT’S IN THIS CHAPTER?
➤ Understanding WordPress Multisite ➤ Diff erences between Multisite and standard WordPress ➤ Installing and confi guring a Multisite network ➤ Coding for Multisite ➤ Multisite database schema
WROX.COM CODE DOWNLOADS FOR THIS CHAPTER The wrox.com code downloads for this chapter are found at www.wrox.com/remtitle .cgi?isbn=9781118442272 on the Download Code tab. The code is in the Chapter 10 download fi le and individually named according to the code fi le names throughout the chapter. WordPress Multisite is a powerful core feature in WordPress. When enabled, Multisite allows you to create multiple websites with a single install of WordPress. This makes it easy to rapidly launch new WordPress websites. A Multisite network can even allow open user and site registration, enabling anyone to create a new site in your network. The largest WordPress Multisite network is WordPress.com, which is a great example of what Multisite can be.
WHAT IS MULTISITE?
Prior to WordPress 3.0, Multisite was called WordPress MU (or multi-user) and was a separate software package that needed to be downloaded and installed. WordPress 3.0 merged MU into the core of WordPress, and WordPress Multisite was born. Multisite is not enabled by default, so it’s important to understand the differences before enabling Multisite in your WordPress installation.
c10.indd 259 12/6/12 1:32 AM 260 ❘ CHAPTER 10 MULTISITE
Multisite Terminology It’s important to understand the terminology used throughout this chapter when working with WordPress Multisite. Two important terms in Multisite are network and site. A network is the entire Multisite installation, or the network. A site is a single site inside the network. Therefore, WordPress Multisite is a network of sites. Another important term is Blog ID. The Blog ID is a unique ID assigned to every new site created in Multisite. Many of the functions and code examples will reference the Blog ID. Sometimes this is also referred to as the site ID. Remember that WordPress was originally built as a blogging platform but has evolved over the years into a full-fl edged content management system. Therefore many of the functions and code in WordPress still reference items as “blogs” when really they are sites.
NOTE Don’t let the term “blog” confuse you. A blog in WordPress Multisite is actually a site in the network. A Blog ID, as referred to by many functions and code examples, is the unique ID of the site in the network.
Diff erences When you install standard WordPress, you are installing a single website to run on WordPress. WordPress Multisite enables you to run an unlimited number of websites with a single install of WordPress. When enabling Multisite, you need to determine how sites will be viewed in WordPress, either using subdomains or subdirectories. The following is an example of both: Subdirectory Example ➤ http://example.com/site1 ➤ http://example.com/site2
Subdomain Example ➤ http://site1.example.com/ ➤ http://site2.example.com/
As you can see, this is a pretty big decision and one that should be carefully considered. With a plugin, there are ways to map top-level domains to any site in your network (i.e., http://mywebsite.com), which is covered later on in this chapter. Themes and plugins are also treated differently in Multisite. Individual site administrators can enable themes and plugins on their site, but they can’t install them. WordPress Multisite also introduces a new user role: Super Admin. Super Admin users have access to the Network Admin section of Multisite. This section is where all Multisite confi guration occurs. Super Admins also have full access to every site in the Multisite network, whereas normal Administrators only have access to the site they are an administrator of.
c10.indd 260 12/6/12 1:32 AM What Is Multisite? ❘ 261
Advantages of Multisite WordPress Multisite has a number of advantages over standard WordPress. The biggest advantage of Multisite is that you have a single install of WordPress to administer. This makes updates for WordPress, themes, and plugins much easier. If you have a WordPress Multisite network of 50 sites, and a plugin update is released, you need to update that plugin only once and it will affect all sites in your network. If each of the 50 sites were a separate install of WordPress, you would have to update that plugin 50 separate times. Aggregating content is also another big advantage. It is very easy to share content between your sites in a Multisite network. For example, if you have 50 sites in your network, you could easily aggregate posts from every site to your main blog to showcase your network of sites and content. The biggest advantage to using Multisite is the speed in which you can launch new sites. With just a few clicks you can create new sites in your network. These sites can share themes, plugins, and even users.
Enabling Multisite Enabling the Multisite feature of WordPress is a pretty straightforward process. The fi rst step is to add the following line of code to your wp-config.php fi le:
define( 'WP_ALLOW_MULTISITE', true );
This line of code should be added just above the comment that reads:
/* That's all, stop editing! Happy blogging. */.
Save your wp-config.php fi le and upload to your server. Now log in to the admin dashboard of WordPress and you’ll notice a new submenu item for Tools ➪ Network Setup, as shown in Figure 10-1. The Network Setup screen will vary depending on your current WordPress setup. If your setup allows it, you will choose either Subdomains or Subdirectories for your Multisite setup. You also need to verify that the Server Address, Network Title, and Admin E-mail Address values are correct. These are fi lled in automatically by WordPress, but you can modify the values if needed. After you have confi rmed that the settings are what you want, click the Install button to install Multisite in WordPress. The fi nal step to enabling Multisite will be presented on the screen; it’s a series FIGURE 10-1: Network Setup of manual changes you need to make to WordPress. The fi rst step is to cre- submenu ate a blogs.dir directory in your /wp-content directory. This new directory will store all media uploaded throughout your Multisite network. All media in Multisite is uploaded to wp-content/blogs.dir/BLOG_ID/files/YEAR/MONTH. Permalinks for media fi les look like this:http://example.com/files/2013/10/Halloween.png .
c10.indd 261 12/6/12 1:32 AM 262 ❘ CHAPTER 10 MULTISITE
The next step is to add some code to your wp-config.php fi le. This code defi nes the base settings for Multisite, and will vary depending on your setup. The following is a code example for a Subdirectory install of Multisite under the example.com domain.
define( 'MULTISITE', true ); define( 'SUBDOMAIN_INSTALL', false ); $base = '/'; define( 'DOMAIN_CURRENT_SITE', 'example.com' ); define( 'PATH_CURRENT_SITE', '/' ); define( 'SITE_ID_CURRENT_SITE', 1 ); define( 'BLOG_ID_CURRENT_SITE', 1 );
The fi nal step is to replace your .htaccess fi le rules with the new rules provided:
RewriteEngine On RewriteBase / RewriteRule îndex\.php$ - [L]
# uploaded files RewriteRule ^([_0-9a-zA-Z-]+/)?files/(.+) wp-includes/ms-files.php?file=$2 [L]
# add a trailing slash to /wp-admin RewriteRule ^([_0-9a-zA-Z-]+/)?wp-admin$ $1wp-admin/ [R=301,L]
RewriteCond %{REQUEST_FILENAME} -f [OR] RewriteCond %{REQUEST_FILENAME} -d RewriteRule ^ - [L] RewriteRule ^[_0-9a-zA-Z-]+/(wp-(content|admin|includes).*) $1 [L] RewriteRule ^[_0-9a-zA-Z-]+/(.*\.php)$ $1 [L] RewriteRule . index.php [L]
These rules may differ depending on your Multisite setup, so make sure you copy the code provided in the Network Setup screen when enabling Multisite in WordPress. After making the required changes, you will be required to log back in to WordPress. The easiest way to tell when Multisite is enabled is through the WordPress admin bar. You’ll notice a new menu item named My Sites. When hovering over this menu, the fi rst Submenu link is Network Admin, which is the main admin dashboard for Multisite. The My Sites menu will also list all sites you are a member of in your network, as shown in Figure 10-2. WordPress Multisite is now enabled and ready to use! FIGURE 10-2: Multisite Network menu WORKING IN A NETWORK
Now that you know how to enable Multisite in WordPress, it’s important to understand how to manage your network. This section covers the Multisite Network Admin section of WordPress and how to manage a network.
c10.indd 262 12/6/12 1:32 AM Working in a Network ❘ 263
Network Admin The WordPress Multisite Network Admin is the central hub for all Multisite management of your network. You can access the Network Admin under the My Sites menu in the WordPress admin bar or by visiting http://example.com/wp-admin/network/. The Network Admin should look very familiar because its layout and style are very similar to the standard WordPress admin dashboard.
Creating and Managing Sites To view a list of all sites in your Multisite Network, visit the Sites menu. Here you will see every site registered in Multisite, regardless of the status of the site. The list screen gives you some important information, such as the site name, last updated date, registered date, and all users that are members of that site. To edit any site’s settings, click on the site name to bring up the Edit Site screen. The Edit Site section allows you to edit all settings of a specifi c site in your network. You’ll notice tabs for each settings section, as shown in FIGURE 10-3: Edit Site section Figure 10-3. The Info tab allows you to edit the domain and path of the site. These two settings are not confi gurable for the main site in your network. You can also change the Registered and Last updated date and timestamps. The fi nal editable item is the Attributes, or site status, setting. Every site in your network can have one of the following fi ve site statuses: 1. Public — Site is public if privacy is set to enable search engines. 2. Archived — Site has been archived and is not available to the public. 3. Spam — Site is considered spam and is not available to the public. 4. Deleted — Site is fl agged for deletion and is not available to the public. 5. Mature — Site is fl agged as mature.
The only two statuses that don’t remove the site from public viewing are Public and Mature. The Users tab allows you to administer what users have access to this site. This section will list all users of the site with their role. You can also add new users to the site. The next section cover users in Multisite in more detail. The Themes tab allows you to enable or disable themes for the site. Enabling a theme on this screen does not actually activate the theme for the site you are editing, but rather, makes that theme an available option for the site administrator to enable should he choose to do so.
c10.indd 263 12/6/12 1:32 AM 264 ❘ CHAPTER 10 MULTISITE
The Settings tab enables you to edit all other settings for the site. There are a lot of options on this screen. As a good rule, if you don’t know what you are changing, you probably shouldn’t change it.
Working with Users and Roles Users in a Multisite network work differently than in standard WordPress. The major difference is that each site in the network can have a different set of users. Users can also be a member of multiple sites in your network and even have a different user role for each site. For example, you could be an Administrator on site A, but only an Author on site X. If Allow New Registrations is enabled under the Network Settings menu, visitors can register new user accounts in WordPress. A New User is not automatically a member of every site in your network, but rather the main (fi rst) site in your network. For example, if your network features two sites, a Halloween site and a Christmas site, any visitor who registers would be a member of the Halloween site but not the Christmas site. Of course, you could always add this user to the Christmas site later. To view all users in your Multisite network, visit the Users menu. Here you will see a list of all users in the network along with their names, e-mail addresses, registered dates, and a list of sites they are members of. If the user is a Super Admin, you will see that information listed next to her username. You can easily add, edit, or delete users from your network in this section.
Themes and Plugins Multisite handles themes and plugins differently than standard WordPress. All sites in your network can run the same plugins and themes, or they can run a completely different set of plugins and themes. The fl exibility of this really showcases the power of Multisite in WordPress.
Themes To view all themes installed in WordPress, visit the Themes menu. The Network Admin Themes section lists all themes in a list similar to the standard WordPress Plugins section. The major difference is that rather than an Activate link for each theme, you’ll notice a Network Enable link instead. Network Enabling any theme listed will make that theme an available option for all sites in your network. This doesn’t actually activate the theme, but rather makes the theme available to site administrators under the Appearance ➪ Themes menu in WordPress. This allows you to control what themes are available for your site administrators to choose from.
Plugins Plugins work differently from themes in Multisite. Plugins can be Network Activated, which means the plugin will run on every site in your network. If a plugin is not Network Activated, it can still be activated at the site level. This means that you can run plugins on any, or all, sites in your network. To view all plugins available for use, visit the Plugins menu. Here you’ll see a list of plugins that have been downloaded to WordPress. Clicking the Network Activate link will activate the plugin across every site in your network. If a plugin is not Network Activated, it will be available to activate at the site level under the standard Plugins menu.
c10.indd 264 12/6/12 1:32 AM Coding for Multisite ❘ 265
NOTE It’s important to verify that a plugin is Multisite-compatible prior to network-enabling the plugin. If the plugin hasn’t been tested on Multisite, or coded properly, there is a chance it could break your network when activated network wide.
Settings The Settings menu lets you set network-wide settings in Multisite. Here you can enable user account registration and even site creation for your users. Enabling both of these features would allow visitors to register user accounts and even create new sites in your network. You can also set what fi le types are allowed for upload, total site upload space, and the max upload fi le size. If you plan on launching a very large Multisite network, limiting site upload space and max upload size could save you a massive amount of disk space. By default, the Plugins menu is hidden from site administrators. This allows only Super Admins to activate and deactivate plugins at the site level. If you want to enable the Plugins menu for regular administrators, you can do so under the Menu Settings section.
Domain Mapping One very common feature for Multisite users is domain mapping. Earlier, you considered the two default site confi gurations for Multisite: Subdirectory or Subdomain. But what if you want each site in your network to have a unique domain name? There’s a plugin for that! The WordPress MU Domain Mapping plugin (http://wordpress.org/extend/plugins/wordpress-mu-domain- mapping/) allows you to do just that. This plugin makes it very easy to attach a top-level domain to any site in your network. The plugin also works with both Subdirectory and Subdomain setups. For example, instead of two sites like http://example.com/brad and http://example.com/myers, you could have http://brad.com and http://myers.com. All URLs will be served up using the top-level domain you have assigned to your sites.
CODING FOR MULTISITE
When Multisite is enabled in WordPress, you can take advantage of an entirely new set of Multisite- specifi c functions and APIs in your themes and plugins. Understanding these new features can help you make your themes and plugins Multisite-compatible.
Blog ID Every site in your Multisite network has a unique ID associated with it. This unique ID is called the Blog ID. Almost every function you work with when writing Multisite-specifi c code will use this Blog ID. This is how WordPress determines what site you want to work with. The Blog ID is also used in the database table prefi x with each new site you create in your network. When you create new sites in Multisite, WordPress creates additional database tables to store that site’s content and settings. For example, if you create a second site in your network, WordPress will
c10.indd 265 12/6/12 1:32 AM 266 ❘ CHAPTER 10 MULTISITE
create new tables prefi xed like wp_2_posts where wp_ is the table prefi x you defi ned when installing WordPress, and 2_ is the Blog ID of the new site.
The Blog ID is stored in the global variable $blog_id, as shown here:
In Multisite, the $blog_id will always be the ID of the current site you are viewing. In standard WordPress, the $blog_id global variable will always be 1.
Common Functions Some common functions are available when working with Multisite. The most important function when working with Multisite is the is_multisite() function, as shown here:
This function determines whether Multisite is enabled and, if so, returns true. Anytime you plan on using Multisite-specifi c functions in WordPress, it’s extremely important that you verify that Multisite is actually enabled before doing so. If Multisite is not enabled, and you call a Multisite function, you will receive an error message and the site will break.
Another useful function for retrieving site-specifi c information is the get_blog_details() function.
The function accepts two parameters: 1. $fields — Blog ID, a blog name, or an array of fi elds to query against 2. $getall — Whether to retrieve all details
Using this function, you can retrieve general site information for any site specifi ed.
Running the preceding code example displays the following results:
stdClass Object ( [blog_id] => 1 [site_id] => 1 [domain] => example.com [path] => /
c10.indd 266 12/6/12 1:32 AM Coding for Multisite ❘ 267
[registered] => 2012-10-31 19:01:47 [last_updated] => 2012-10-31 19:01:49 [public] => 1 [archived] => 0 [mature] => 0 [spam] => 0 [deleted] => 0 [lang_id] => 0 [blogname] => Halloween Site [siteurl] => http://example.com [post_count] => 420 )
Switching and Restoring Sites One of the main advantages to using WordPress Multisite is how easy it is to aggregate content, and other data, between different sites in your Multisite network. There are two primary functions you can use to retrieve data from other sites in your network. The fi rst of these is theswitch_to_blog() function. This function enables you to switch to any site in your network:
The function accepts two parameters: 1. $blog_id — The ID of the site you want to switch to. 2. $validate — Whether to check if the site exists before proceeding. The default is false.
The second function is restore_current_blog(). This function does exactly what it sounds like: it restores the previous site after a switch_to_blog() function is called. There are no parameters for this function; simply call it after you are done gathering content and data from the site. Consider the following example that uses these two functions. In this example, you’ll create a custom shortcode to retrieve the latest fi ve posts from a site in your network:
add_shortcode( 'show_network_posts', 'prowp_get_network_posts' );
First, register a new shortcode called show_network_posts using the add_shortcode() function. The new shortcode will accept one parameter, which is the Blog ID you want to display the latest posts from. Next, you’ll create the function to return the latest posts from a site in your network.
function prowp_get_network_posts( $atts ) { extract( shortcode_atts( array( 'blog_id' => '1' ), $atts ) );
//verify Multisite is enabled if ( is_multisite() ) {
//switch to blog ID passed in
c10.indd 267 12/6/12 1:32 AM 268 ❘ CHAPTER 10 MULTISITE
switch_to_blog( absint( $blog_id ) );
//create a custom loop $recent_posts = new WP_Query(); $recent_posts->query( 'posts_per_page=5' );
$site_posts = '';
//star the custom loop while ( $recent_posts->have_posts() ) : $recent_posts->the_post();
//store the recent posts in a variable $site_posts .= '
' .get_the_title().'
';
endwhile;
//restore the current site restore_current_blog();
}
//return the posts return $site_posts;
}
As always, you need to verify that Multisite is enabled using the is_multisite() function check. Next, use the switch_to_blog() function to switch to the Blog ID passed in through the shortcode. If the user does not set the Blog ID in the shortcode, it will default to Blog ID 1. Now that you’ve switched to the site, you’ll create a custom loop using WP_Query to pull the latest posts from the site. Next, loop through the WP_Query results, storing each post in a variable called $site_posts.
After the loop has completed, you need to run restore_current_blog() to switch back to the previous site you were viewing. If you do not run this function, WordPress stays on Blog ID 10, so any subsequent loops or custom code will assume you are still on Blog ID 10, when in fact you are not. The fi nal step is to return the variable $site_posts, which contain the latest fi ve posts from Blog ID 10. That’s it! Now you can easily display the most recent blog posts from any site in your network using the shortcode: [show_network_posts blog_id="10"]. Listing 10-1 shows the entire code packaged up in a plugin.
LISTING 10-1: Multisite shortcode example (prowp2-multisite-shortcode.zip)
c10.indd 268 12/6/12 1:32 AM Coding for Multisite ❘ 269
Author URI: http://strangework.com License: GPLv2 */
add_shortcode( 'show_network_posts', 'prowp_get_network_posts' );
function prowp_get_network_posts( $atts ) { extract( shortcode_atts( array( 'blog_id' => '1' ), $atts ) );
//verify Multisite is enabled if ( is_multisite() ) {
//switch to blog ID passed in switch_to_blog( absint( $blog_id ) );
//create a custom loop $recent_posts = new WP_Query(); $recent_posts->query( 'posts_per_page=5' );
$site_posts = '';
//star the custom loop while ( $recent_posts->have_posts() ) : $recent_posts->the_post();
//store the recent posts in a variable $site_posts .= '
' .get_the_title().'
';
endwhile;
//restore the current site restore_current_blog();
}
//return the posts return $site_posts;
}
?>
The switch_to_blog() function is not just limited to site content, but can also retrieve other WordPress data including menus, widgets, sidebars, and more. Basically, any data stored in the content database tables (wp_blogid_tablename) is available when using switch_to_blog(). Consider a different example. This time you’ll retrieve a specifi c menu from a site in your Multisite network.
c10.indd 269 12/6/12 1:32 AM 270 ❘ CHAPTER 10 MULTISITE
wp_nav_menu( 'Main Menu' );
restore_current_blog(); ?>
First run switch_to_blog() to switch to Blog ID 10. Next, use the wp_nav_menu() WordPress function to display a menu named Main Menu from the site. Finally, run restore_current_blog() to reset back to the current site you are viewing. The preceding code will display the Main Menu nav menu from Site ID 10 anywhere you run this code.
It’s important to note that the switch_to_blog() function has the potential to generate very large SQL queries, which could cause performance issues with WordPress. It’s best to cache any data retrieved using this function in a transient, which enables data to be temporarily stored as a cached version. WordPress transients are covered in detail in Chapter 11.
Another important note is that switch_to_blog() only changes the database context; it does not inherit the entire site confi guration.. This means that a site’s plugins are not included in a switch. If you switch to a site and try to execute a function specifi c to a plugin that is not enabled, you will receive an error message.
Creating a New Site You’ve learned how to create new sites in the Network Admin of Multisite, so now you will see how to create new sites via code. To do so, you’ll use the wpmu_create_blog() function.
This function accepts six parameters: 1. $domain — The domain of the new site 2. $path — The path of the new site 3. $title — The title of the new site 4. $user_id — The user ID of the user account who will be the site admin 5. $meta — Additional meta information 6. $site_id — The site ID of the site to be created
Only the fi rst four parameters are required; the last two are optional. The $site_id parameter is only used if you plan to run multiple WordPress Networks inside a single installation of WordPress. If the new site is created successfully, the function will return the newly created Blog ID of the site.
For example, you can build a plugin that uses the wpmu_create_blog() function to create new sites in your Multisite network, as follows:
add_action( 'admin_menu', 'prowp_multisite_create_menu' );
function prowp_multisite_create_menu() {
//create custom top-level menu
c10.indd 270 12/6/12 1:32 AM Coding for Multisite ❘ 271
add_menu_page( 'Multisite Create Site Page', 'Multisite Create Site', 'manage_options', 'prowp-network-create', 'prowp_multisite_create_sites' );
}
First, you’ll create a new top-level menu called Multisite Create Site. This menu will link to a custom function called prowp_multisite_create_sites(), which will allow you to create sites in the network. Go ahead and create that function as follows:
function prowp_multisite_create_sites() { //check if multisite is enabled if ( is_multisite() ) {
Remember to always verify that Multisite is enabled using the is_multisite() function. Next, you’ll add the code to retrieve the submitted form fi eld values and create a new site in Multisite:
//if the form was submitted lets process it if ( isset( $_POST['create_site'] ) ) {
//populate the variables based on form values $domain = strip_tags( $_POST['domain'] ); $path = strip_tags( $_POST['path'] ); $title = strip_tags( $_POST['title'] ); $user_id = absint( $_POST['user_id'] );
//verify the required values are set if ( $domain && $path && $title && $user_id ) {
//create the new site in WordPress $new_site = wpmu_create_blog( $domain, $path, $title, $user_id );
//if successfully display a message if ( $new_site ) {
echo '
New site ' .$new_site . ' created successfully!
';
}
//if required values are not set display an error } else {
echo '
New site could not be created. Required fields are missing
';
}
}
First check if $_POST['create_site'] is set. This fi eld will be set only if the form has been submitted. Next you’ll populate the variable values with the data submitted via the form. Notice that you’re using the proper sanitizing functions to verify that the values submitted do not contain
c10.indd 271 12/6/12 1:32 AM 272 ❘ CHAPTER 10 MULTISITE
HTML and PHP code. You also verify the user_id value is a positive integer using the WordPress absint() function. Now that the variables are set, you want to verify they each have a value. If you are missing data for any of the four required parameters an error message is displayed. After you’ve verifi ed that the values exist, it’s time to execute the wpmu_create_blog() function to create the new site. If the new site is created successfully the variable $new_site will contain the new Blog ID of the site. Now you will build the form for the new site fi elds using the following:

Create New Site

Domain

Path

Title

User ID

This is standard HTML to collect the required fi eld data for creating the new site in Multisite. You can now easily create new sites in your network using the full plugin shown in Listing 10-2.
LISTING 10-2: Create sites in Multisite example (prowp2-multisite-create-site.zip)
c10.indd 272 12/6/12 1:32 AM Coding for Multisite ❘ 273
Version: 1.0 Author: Brad Williams Author URI: http://strangework.com License: GPLv2 */
add_action( 'admin_menu', 'prowp_multisite_create_menu' );
function prowp_multisite_create_menu() {
//create custom top-level menu add_menu_page( 'Multisite Create Site Page', 'Multisite Create Site', 'manage_options', 'prowp-network-create', 'prowp_multisite_create_sites' );
}
function prowp_multisite_create_sites() {
//check if multisite is enabled if ( is_multisite() ) {
//if the form was submitted let's process it if ( isset( $_POST['create_site'] ) ) {
//populate the variables based on form values $domain = strip_tags( $_POST['domain'] ); $path = strip_tags( $_POST['path'] ); $title = strip_tags( $_POST['title'] ); $user_id = absint( $_POST['user_id'] );
//verify the required values are set if ( $domain && $path && $title && $user_id ) {
//create the new site in WordPress $new_site = wpmu_create_blog( $domain, $path, $title, $user_id );
//if successfully display a message if ( $new_site ) {
echo '
New site ' .$new_site. ' created successfully!
';
}
//if required values are not set display an error } else {
echo '
New site could not be created. Required fields are missing
';
}
} continues
c10.indd 273 12/6/12 1:32 AM 274 ❘ CHAPTER 10 MULTISITE
LISTING 10-2 (continued)
?>

Create New Site

Domain

Path

Title

User ID

echo '
Multisite is not enabled
';
}
} ?>
Network Admin Menus Earlier this chapter covered the Multisite Network Admin section of WordPress. This Dashboard is where all Network Settings are confi gured. As in standard WordPress, you can add menus and submenus to the Network Admin screen. To do this, you’ll use the network_admin_menu action hook, as shown here:
add_action( 'network_admin_menu', 'prowp_add_network_settings_menu' );
c10.indd 274 12/6/12 1:32 AM Coding for Multisite ❘ 275
The network_admin_menu action hook is triggered after the default network admin menu structure is in place. The second parameter is the custom function prowp_add_network_settings_menu(), which will register your new menu.
function prowp_add_network_settings_menu() {
//add settings menu add_menu_page( 'ProWP2 Options Page', 'ProWP2 Options', 'manage_options', 'prowp-network-settings', 'prowp_network_settings' );
}
As you can see, registering the new menu is exactly the same as registering a standard WordPress menu. In this example, you use the add_menu_page() function to create a new top-level menu in the Network Admin, as shown in Figure 10-4. Just as easily as you can add a new top-level menu to the Network Admin, you can add submenu items to existing menus. To do this, you’ll use the add_submenu_page() function, as shown here:
function prowp_add_network_settings_menu() {
//add Settings submenu add_submenu_page( 'settings.php', 'ProWP2 Options Page', 'ProWP2 Options', 'manage_options', 'prowp-network-settings', 'prowp_network_settings' );
}
This function works exactly as in standard WordPress. The fi rst parameter, settings.php in this case, is the most important. That value tells the function what top-level menu to add your submenu to. In this example, you added a submenu item called ProWP2 Options to the Settings menu in the Network Admin. The following is a list of fi le names that you can add submenus to:
➤ index.php — Add submenu to the Dashboard menu ➤ sites.php — Add submenu to the Sites menu ➤ users.php — Add submenu to the Users menu FIGURE 10-4: Network Admin ➤ themes.php — Add submenu to the Themes menu top-level menu ➤ plugins.php — Add submenu to the Plugins menu ➤ settings.php — Add submenu to the Settings menu ➤ update-core.php — Add submenu to the Updates menu
As a general rule, it’s best to add your Network Settings as a submenu of the Settings menu in the Network Admin. This is where most users will look for plugin settings, just like in standard WordPress.
c10.indd 275 12/6/12 1:32 AM 276 ❘ CHAPTER 10 MULTISITE
Multisite Options When storing options in Multisite, it’s important to use the proper functions to store the options in the proper place. The question you should ask yourself is who should control the settings value. If the setting is specifi c to each site in the network, and can vary between sites, then you should store your options as site options. If the setting should be a network-wide setting that shouldn’t vary between sites, then you should store your options as network options.
Site Options To store site-specifi c options in Multisite, you can utilize the *_blog_option() functions. The following is a list of each function:
➤ add_blog_option() — Creates a new option ➤ update_blog_option() — Updates an option and creates it if it doesn’t exist ➤ get_blog_option() — Loads a site option ➤ delete_blog_option() — Deletes a site option
These functions work almost identically to the standard WordPress option functions; the major difference is that the functions require a $blog_id parameter to be defi ned, as shown here:
The $key parameter is the option name you want to set and the $value parameter is the value to set for the option.
Retrieving a site option is just as easy. The following example shows you how to use get_blog_ option() to retrieve site-specifi c options for Blog ID 10:
Site ID: ' .$blog_id .'
'; echo '
Site Name: ' .get_blog_option( $blog_id, 'blogname' ) .'
'; echo '
Site URL: ' .get_blog_option( $blog_id, 'siteurl' ) .'
'; ?>
Network Options To store network-wide options in Multisite, you can utilize the *_site_option() functions. The follow list describes each function:
➤ add_site_option() — Creates a new network option ➤ update_site_option() — Updates a network option and creates it if it doesn’t exist ➤ get_site_option() — Loads a network option ➤ delete_site_option() — Deletes a network option
c10.indd 276 12/6/12 1:32 AM Coding for Multisite ❘ 277
These functions work almost identically to standard WordPress option functions, but the option values are stored in the wp_sitemeta Multisite database table. You can use these functions to store global Multisite settings that should be the same for all sites in your network.
Notice you do not need to defi ne the Blog ID when adding a network option. Because you are storing a network option, it doesn’t matter what Blog ID the code is being executed from.
If Multisite is not enabled, and your code calls one of the *_site_option() functions, WordPress will fall back to using standard *_option() functions such as add_option().
Network Options Example Now that you understand how to create and retrieve network options, let’s build a simple network options plugin for Multisite. In this example, you are going to build a plugin to store network wide options. The plugin will degrade gracefully, so if the user is not running Multisite, the options will be stored as standard WordPress options. The fi rst step in your plugin will be to add the Network Settings menu.
add_action( 'init', 'prowp_network_settings_menu' );
function prowp_network_settings_menu() {
if ( is_multisite() ) {
//Multisite is enabled so add menu to Network Admin add_action( 'network_admin_menu', 'prowp_add_network_settings_menu' );
} else {
//Multisite is NOT enabled so add menu to WordPress Admin add_action( 'admin_menu', 'prowp_add_network_settings_menu' );
}
}
The init action hook is used to call your custom function to register the network options menu. Notice how the is_multisite() function is used in the preceding example. If the user has Multisite enabled, the new menu will be added to the Network Admin of Multisite. If the user does not have Multisite enabled, the menu will be added as a standard WordPress menu. This code is important to preserve compatibility regardless of whether Multisite is enabled or not. Now that you’ve registered the proper menu action hook, you need to create the custom function to register the new menu.
function prowp_add_network_settings_menu() {
//add settings menu add_menu_page( 'Network Options Page', 'Network Options',
c10.indd 277 12/6/12 1:32 AM 278 ❘ CHAPTER 10 MULTISITE
'manage_options', 'prowp-network-settings', 'prowp_network_settings' );
}
The preceding code uses the add_menu_page() function to create a new top-level menu labeled Network Options. Now that the menu has been created, you need to create the actual settings form.
//generate the settings page function prowp_network_settings() { ?>

Network Settings

//create nonce hidden field for security wp_nonce_field( 'save-network-settings', 'prowp-network-plugin' ); ?>

API Key:

Network Holiday

Rage Mode: /> Enabled

c10.indd 278 12/6/12 1:32 AM Coding for Multisite ❘ 279

You’ll use a standard HTML form to manage the Network Settings. The options will be stored as an array in a single option, as described in the Plugin Settings section of Chapter 8, “Plugin Development.” The fi rst step is to load any existing setting values. Using the get_site_option() function, you’ll load the prowp_network_settings value, which is your options array, if any exists. Next, set each option value into individual variables. Before you actually create your form, use the wp_nonce_field() function to create a hidden form fi eld nonce for security. Now it’s time to build the form. The fi rst form fi eld is an API Key, which is a standard text fi eld. The second form fi eld is a select fi eld. Notice how you use the selected() function to determine which option should be selected. The fi nal setting is a check box for Rage Mode. This option uses the checked() function to determine if the option is checked or not. Because you are using a standard HTML form, you’ll need to add a submit button to submit the form values. Now that your Network Settings form is set up, you’ll need to create the function to process and save the form data.
add_action( 'admin_init', 'prowp_save_network_settings' );
//save the option values function prowp_save_network_settings() {
//if network settings are being saved, process it if ( isset( $_POST['network_settings'] ) ) {
//check nonce for security check_admin_referer( 'save-network-settings', 'prowp-network-plugin' );
//store option values in a variable $network_settings = $_POST['network_settings'];
//use array map function to sanitize option values $network_settings = array_map( 'sanitize_text_field', $network_settings );
//save option values update_site_option( 'prowp_network_settings', $network_settings );
}
}
You’ll use the admin_init hook for your custom function for saving the form data. The fi rst step is to verify that form values have been posted. If the form wasn’t submitted, there’s nothing for you to process. You’ll do this by verifying that $_POST['network_settings'] is actually set by using the
c10.indd 279 12/6/12 1:32 AM 280 ❘ CHAPTER 10 MULTISITE
isset() PHP function. Once you’ve verifi ed that there is form data to process, you need to check your nonce using the check_admin_referer() function.
Once the nonce check passes, you’ll store the post data in the $network_settings variable. Because the data that you are processing is user-provided, it’s important to sanitize that data before storing it in the database. In this example, you’ll use the array_map() PHP function, which will send each individual value of the array to any function specifi ed, in this case the sanitize_text_field() WordPress function. Now that your data is properly sanitized, you’ll save the option using the update_site_option() function. That’s it! You have just built a fully functional Network Settings section that is fully compatible with standard WordPress. If the user is running Multisite, the menu will show in the Network Admin and the option values will be stored in the wp_sitemeta table. If the user is not running Multisite, the menu will show in the standard WordPress Admin Dashboard and the option values will be stored in the wp_options table. Listing 10-3 shows the fi nalized plugin.
LISTING 10-3: Multisite network settings (prowp2-multisite-network-settings.zip)
add_action( 'init', 'prowp_network_settings_menu' );
function prowp_network_settings_menu() {
if ( is_multisite() ) {
//Multisite is enabled so add menu to Network Admin add_action( 'network_admin_menu', 'prowp_add_network_settings_menu' );
} else {
//Multisite is NOT enabled so add menu to WordPress Admin add_action( 'admin_menu', 'prowp_add_network_settings_menu' );
}
}
function prowp_add_network_settings_menu() {
//add settings menu
c10.indd 280 12/6/12 1:32 AM Coding for Multisite ❘ 281
add_menu_page( 'Network Options Page', 'Network Options', 'manage_options', 'prowp-network-settings', 'prowp_network_settings' );
}
//generate the settings page function prowp_network_settings() { ?>

Network Settings

//create nonce hidden field for security wp_nonce_field( 'save-network-settings', 'prowp-network-plugin' ); ?>

API Key:

Network Holiday

Rage Mode: /> Enabled

continues
c10.indd 281 12/6/12 1:32 AM 282 ❘ CHAPTER 10 MULTISITE
LISTING 10-3 (continued)

add_action( 'admin_init', 'prowp_save_network_settings' );
//save the option values function prowp_save_network_settings() {
//if network settings are being saved, process it if ( isset( $_POST['network_settings'] ) ) {
//check nonce for security check_admin_referer( 'save-network-settings', 'prowp-network-plugin' );
//store option values in a variable $network_settings = $_POST['network_settings'];
//use array map function to sanitize option values $network_settings = array_map( 'sanitize_text_field', $network_settings );
//save option values update_site_option( 'prowp_network_settings', $network_settings );
}
}
Users in a Network When working with users in a Multisite network, you should always verify that a user is a member of a specifi c site. To do this, you’ll use the is_user_member_of_blog() function.
The function accepts two optional parameters. The fi rst parameter is the user ID of the user you want to check. If not set, the function will check the current user. The second parameter is the Blog ID. If this parameter isn’t set, the function defaults to the current site you are on.
The preceding code example will verify that the user is a member of the current site they are viewing.
c10.indd 282 12/6/12 1:32 AM Coding for Multisite ❘ 283
Now that you understand how to verify that a user is a member of a site, you can add users to a site with the add_user_to_blog() function:
The function accepts three parameters: 1. $blog_id — The ID of the site you want to add the user to 2. $user_id — The ID of the user to add 3. $role — The role the user will have on the site Now build a plugin that automatically adds a logged-in user to any site that the user visits in your Multisite network, as follows:
add_action( 'init', 'prowp_multisite_add_user_to_site' );
First, you’ll use the init action hook to execute your custom function to add users to the site.
function prowp_multisite_add_user_to_site() {
//verify user is logged in before proceeding if( !is_user_logged_in() ) return false;
//load current blog ID and user data global $current_user, $blog_id;
//verify user is not a member of this site if( ! is_user_member_of_blog() ) {
//add user to this site as a subscriber add_user_to_blog( $blog_id, $current_user->ID, 'subscriber' );
}
}
The fi rst step is to verify the user is logged in, and if not exit the function by returning false. Next you’ll call the global $current_user and $blog_id variables. These variables store the data of the current logged-in user and the Blog ID the user is currently viewing. Next confi rm that the user is not a member of the current site using the is_user_member_of_blog() function. The fi nal step is to add the user to the site using the add_user_to_blog() function. In this example you set the role of the user to subscriber, but you could easily change this to any role you’d like. That’s it! For this plugin to work across your entire network you’ll either need to Network Activate the plugin or upload to the /mu-plugins directory. Either option will force the plugin to run across all sites in your network. The fi nalized plugin is shown in Listing 10-4.
c10.indd 283 12/6/12 1:32 AM 284 ❘ CHAPTER 10 MULTISITE
LISTING 10-4: Automatically add users to sites in Multisite (prowp2-multisite-add-users.zip)
add_action( 'init', 'prowp_multisite_add_user_to_site' );
function prowp_multisite_add_user_to_site() {
//verify user is logged in before proceeding if( !is_user_logged_in() ) return false;
//load current blog ID and user data global $current_user, $blog_id;
//verify user is not a member of this site if( ! is_user_member_of_blog() ) {
//add user to this site as a subscriber add_user_to_blog( $blog_id, $current_user->ID, 'subscriber' );
}
} ?>
Now that you understand how to add users to a site, you can remove users from a site. To remove users you’ll use the remove_user_from_blog() function:
This function accepts three parameters: 1. $user_id — ID of the user you want to remove 2. $blog_id — ID of the blog to remove the user from 3. $reassign — ID of a user to reassign posts to
The $user_id and $blog_id parameters are required. The $reassign parameter is optional. This parameter should be the ID of the user you want to reassign posts to when removing a user.
c10.indd 284 12/6/12 1:32 AM Coding for Multisite ❘ 285
NOTE Remember that adding and removing users from a site in Multisite is not actually creating or deleting the user in WordPress, but instead adding or removing them as a member of a specifi c site.
To retrieve a list of all sites a user belongs to you’ll use the get_blogs_of_user() function. This function returns an array of objects containing the details of each site the user has access to. Here’s an example:
echo 'User '.$user_id.'\'s blogs:
';
foreach ( $user_blogs AS $user_blog ) {
echo '
' .$user_blog->blogname .'
';
}
echo '
'; ?>
The preceding code retrieves the site data for all sites that user ID 1 is a member of. You then loop through the returned array, displaying the blogname value for each site.
Super Admins Earlier this chapter covered the new user role introduced in Multisite, the Super Admin role. Any user set to the Super Admin role has full control over every site in your Multisite network. Users set to the Super Admin role also have full control over what themes and plugins are available, all users, and network-wide settings.
To retrieve a list of all Super Admins in Multisite you’ll use the get_super_admins() function. This function accepts no parameters and returns an array of all Super Admin usernames in your network. Here’s an example:
The preceding code example would return the following array of Super Admins: Array
( [0] => admin [1] => michael_myers )
c10.indd 285 12/6/12 1:32 AM 286 ❘ CHAPTER 10 MULTISITE
You can also check a specifi c user ID to determine if this user is a Super Admin in your network. To do so, use the is_super_admin() function, as shown here:
if ( is_super_admin( $user_id ) ) { echo 'User is a Super Admin'; } ?>
The preceding code example checks if User ID 1 is a Super Admin. The function accepts a $user_id as an optional parameter. If the user ID isn’t passed to the function, it defaults to the current user. Now that you understand how to check for Super Admins, you can make a user a Super Admin. You can easily assign an existing user to the Super Admin role by using the grant_super_admin() function. This function accepts a single required parameter, which is the user ID you want to add to the Super Admin role.
You can also easily remove a user from the Super Admin role with the revoke_super_admin() function. As in the preceding code, this function accepts a single parameter, which is the user ID you want to remove from the Super Admin role:
Both of these functions are located in wp-admin/includes/ms.php. This means that these functions are not available on the public side of your website and can only be used on the admin side.
Network Stats Multisite features various functions to generate stats about your network. The get_blog_count() function returns the total number of sites in your network. To return the total number of users in your network, use the get_user_count() function.
echo '
Total sites: ' .$site_count .'
'; echo '
Total users: ' .$user_count .'
'; ?>
c10.indd 286 12/6/12 1:32 AM Multisite Database Schema ❘ 287
You can also use the get_sitestats() function to retrieve both values at once in an array.
echo '
Total sites: ' .$network_stats['blogs'] .'
'; echo '
Total users: ' .$network_stats['users'] .'
'; ?>
MULTISITE DATABASE SCHEMA
WordPress Multisite features a different database schema from standard WordPress. When enabling Multisite, WordPress creates the necessary tables in your database to support Multisite functionality.
Multisite-Specifi c Tables WordPress stores global Multisite settings in centralized tables. These tables are created only when Multisite is enabled and installed, excluding the wp_users and wp_usermeta tables, which exist in standard WordPress.
➤ wp_blogs — Contains each site created in Multisite. ➤ wp_blog_versions — Contains the current database version of each site in the network. ➤ wp_registration_log — A log of all users registered and activated in WordPress. ➤ wp_signups — Contains users and sites registered using the WordPress registration process. ➤ wp_site — Contains the primary site’s address information. ➤ wp_sitecategories — Contains global terms. Only exists if global terms have been enabled in WordPress. ➤ wp_sitemeta — Contains option data for the network, including Super Admin accounts. ➤ wp_users — Contains all users registered in WordPress. ➤ wp_usermeta — Contains all metadata for user accounts in WordPress.
As you have probably noticed, some important WordPress tables are missing. The rest of the tables created for Multisite are site-specifi c.
Site-Specifi c Tables Every site in your network features its own set of site-specifi c database tables. These tables contain the content and settings specifi c to that individual site. Remember that these tables are prefi xed with the $table_prefix value defi ned in wp-config.php, followed by the $blog_id and then the table name.
c10.indd 287 12/6/12 1:32 AM 288 ❘ CHAPTER 10 MULTISITE
➤ wp_2_commentmeta
➤ wp_2_comments
➤ wp_2_links
➤ wp_2_options
➤ wp_2_postmeta
➤ wp_2_posts
➤ wp_2_terms
➤ wp_2_term_relationships
➤ wp_2_term_taxonomy
Every time you create a new site in your Multisite network, WordPress will create the preceding nine tables in your database for the new site. As you can see, these tables can make your database quickly grow in size. That’s why the only limitation to WordPress Multisite is the server resources available for your network of sites. If your network contains 1,000 sites, your database would have more than 9,000 tables. Obviously a network of this size would not work well on a small, shared hosting account. In Chapter 6, “Data Management,” you covered the importance of using the WordPress database class when querying the database directly. This is especially important in Multisite since the table prefi x contains the Blog ID of the site you are viewing. When writing a custom query, you should always prefi x the table reference with $wpdb->, which will include the site ID if you are running Multisite. As an example, $wpdb->posts would query the wp_2_posts table above, assuming you are working on Blog ID 2 in your network.
SUMMARY
WordPress Multisite is an amazing feature of WordPress with limitless possibilities. Now that Multisite is a core WordPress feature, many users are converting their standard WordPress website to a Multisite network to take advantage of the rapid site deployment features and network capabilities. As more and more users are becoming familiar with the power of Multisite, its use is growing at a very rapid pace. When developing for WordPress, it’s very important to think about Multisite and how your code can utilize these powerful Multisite features covered in this chapter. As a WordPress user, it’s also very important to verify the themes and plugins you are using are Multisite compatible. In the next chapter you’ll cover Content Aggregation. You’ll learn how to work with external APIs to import data from various sources into your website, social media button integration, and understanding different advertising methods and how to monetize your website.
c10.indd 288 12/6/12 1:32 AM 11 Content Aggregation
WHAT’S IN THIS CHAPTER?
➤ Getting your content noticed ➤ Importing various sources into your WordPress site ➤ Using WordPress to cache remote content ➤ Understanding diff erent advertising methods to monetize your website When we began writing this book three years ago, “content aggregation” was viewed as a set of mechanisms to keep your WordPress site updated with information scattered across a rapidly growing number of social networks, and to feed WordPress content updates into those same networks. Sometimes WordPress was the source, sometimes the destination, but the focus was on moving content around — and in so doing, a bit of advice was overlooked in Chapter 1, namely, that sometimes context is as important as the actual content. “Content aggregation” is about how and where you want to direct your audience, and for what purposes. A brief look at what’s changed between editions sets the context for this: Facebook has reached close to a billion users. Twitter sends hashtags in trending motion, and most large content sites have vanity URL shorteners to supplant bit.ly. Google, Bing, and Yahoo are the somewhat lopsided three legs of search. There’s one invariant over time: your WordPress site represents the sum total of your expertise, personal brand, curated content, and design. It is the thing you put in a registration form fi eld labeled “Personal Website” or “Business Website,” and that distinction may help shape the way you manage content aggregation. If your website is about you as an individual, and you see WordPress as an additional vehicle to reach your audience, then you’ll be pulling content in from other sources to populate your WordPress site. Your goal typically is to grow an audience, with less concern for where that audience resides on the web. On the other hand, if your website is about your business or your personal brand as a consultant or expert, or even
c11.indd 289 12/6/12 1:32 AM 290 ❘ CHAPTER 11 CONTENT AGGREGATION
just a landing page for valuable advertising, then you’ll want to focus your audience on your own website. Facebook and Twitter are additional conduits for attracting readers whom you’ll want to click through to your WordPress site. As you evaluate the inbound and outbound aggregation methods in this chapter, think about their effect on reaching your audience: Is WordPress the only channel, or is it one of many channels? This chapter discusses pulling content from external locations — typically social networking destinations — into your website, and conversely, taking your own content and publishing it through social sites or feeds. In particular, you will cover YouTube, Twitter, Facebook, and subscription feeds, since they are the most common. You’ll also consider how to utilize other content sites with their own best of breed and open APIs such as Google Maps, and how you can use the WordPress API to integrate other sources. You’ll start with leveraging social networks to get your site and content noticed through outbound content aggregation.
GETTING NOTICED
Nearly all websites exist so that visitors will transact business, whether that business involves goods, services, or your own brand. Before any transaction can happen, however, people have to be able to fi nd your website. This section is about promoting that brand and your site on the web through content sharing and social networks, not search engine optimization or “SEO.” SEO and getting your site discovered are covered in Chapter 12. Promoting your online identity is one of the major reasons to amass your online interactions into one place. You can collect all of your social media interactions on your website to showcase your professional involvement in a community or profession. This can highlight your expertise in one or more specifi c areas as well as expand your potential audience to different groups. It can really function as a type of business networking among different potential readership groups. Even if you’re not using a public persona for business purposes, the same goal of centralizing all of your online activities amplifi es the benefi ts to your hobbies or your personal passion. If you participate in social networks for home beer-brewing, why not aggregate those activities into one location? If you attract attention because of your witty insight or accurate and knowledgeable information, aggregation is one way to become recognized as an expert in your fi eld of interest. A nice side effect of this aggregation effect is that the larger the number of links that point back to your website, the more the popular search engines will fi nd your site, as covered in Chapter 12. Collecting information from multiple sites into your WordPress site makes it easier for others to fi nd that information. Your readers or potential audience don’t have to keep tabs on all the different places in which your updates could be broadcast or shared. In the same vein, how will clients know to check your latest YouTube promotional video if they do not know it is even available? Collecting this information into a primary source brings all these different data points in front of your audience’s eyes through content aggregation. And in the end, it drives traffi c to your site rather than away from it, because your site becomes the one true source. This is a classic long tail content problem, and is worth discussing a little more. Your website is just one source of content in hundreds of millions out there. But the people you intersect and actively
c11.indd 290 12/6/12 1:32 AM Getting Noticed ❘ 291
communicate with, and the set of those people’s friends and families (the “closure of the set” if you’re an honorary advanced math geek), builds an audience: your audience. Aggregating your content is about building this audience by showing up in multiple places with appropriate content, context, and granularity of updates. Tweeting about recent blog posts, or importing blog post sum- maries into Facebook, for example, are easy ways to spread the word. Incorporating professional organizations that strengthen your own professional reputation furthers this goal. Furthermore aggregation is not simply talking about accumulating social network content but also using websites that provide a functionality, geophysical content or a service that is incorporated into your website. Google Maps is an obvious addition so clients and customers can fi nd your business; so is including Twitter discussions by or about your brand or containing a relevant hashtag. In the end, having more functionality on your site is still marketing. You are either trying to get your site to be more full featured and attractive to your potential clients and customers, or you are leveraging a third-party content source to provide some value.
Social Media Buttons Marketing is marketing — somehow you have to get your website noticed. A great way — perhaps the best way — to get your content noticed and generate more traffi c to your site is to use the power of the social networking sites. First, you have to have good, interesting content on your site. But unlike Field of Dreams, if you built it, they will not necessarily come. You have to advertise. Of course, an ambitious and loyal visitor may take the link to your content and submit it to the Internet at large, but why not make it even easier? Adding social media buttons to your WordPress site makes it easy for readers to include your content in their rankings, ratings, or aggregations, or simply to broadcast to their audience, “Hey people, I like this.” Getting consumers to share their preferences and point back to your content is the core idea of the “long tail” of content; without recommendations from similarly like-minded people, your content never gets discovered. This is true for music, movies, or blogs. So why not make it a one-click event to share your content on your visitors’ own social streams?
The ShareThis plugin (http://wordpress.org/extend/plugins/share-this/) does just this. The Sociable plugin supports links to nearly 120 different social networking channels for your visitors to share your content. This plugin is confi gurable and has a decent control panel. You can confi gure which sites are enabled for sharing, allowing you to tailor the destination site list for your audience or just your own preferences. There are also several options for controlling the rendering of the social networking icons on your site, as well as some additional styling options. The default options provide a nice sharing FIGURE 11-1: ShareThis social networking button under a snippet at the bottom of each post, as shown WordPress post in Figure 11-1.
c11.indd 291 12/6/12 1:32 AM 292 ❘ CHAPTER 11 CONTENT AGGREGATION
Most admirable about this plugin is the simplicity. Out of the box, it just works, and it works as advertised. Visitors can read some of your great content and decide to share it on Pinterest. They simply need to click the Pinterest icon and log in to Pinterest. It is that simple.
Feeding WordPress Upstream If you adopt the notion that your WordPress site is the eventual destination for your audience, then your presence on Facebook, Twitter, and Pinterest is “upstream” from that click-through target. While you benefi t from readers sharing content via the social media buttons, you can also feed entire posts, lead-ins, or post titles to your other online profi les. Getting your updates on Twitter can be as simple or complex as you like. In the corner case simply tweet about your latest post, using a URL shortener to open up tweet room for hashtags, comments, or a witty cross-reference. If you prefer to have your Twitter account announce each new post on your WordPress site, check out a plugin such as Tweetily (http://wordpress.org/extend/ plugins/tweetily-tweet-wordpress-posts-automatically/) to construct tweets from post titles and your introductory or hashtag text. Sending your post content off to Facebook prompts another “where do I want my audience to end up” thought exercise. If you automatically re-post WordPress content into your Facebook newsfeed, then the Facebook audience has no reason or need to come back to your WordPress site, and you may lose commenters, readers, or possible click-throughs to other content. You’re effectively fragmenting your audience by sharing content, however counterintuitive that seems. On the other hand, if your Facebook audience is a source of new readers who may discover you via a friend of a friend or because someone “liked” your post, then feeding your posts up to Facebook can add to your audience. There’s a middle ground if you decide to create a Facebook page for your WordPress site, neatly working around the bidirectional nature of “friend” relationships and the limit on the number of friend connections you can have. Whether it’s a page or your personal account, the simplest way to get content from your WordPress site into Facebook is via the Facebook RSS Graffi ti application (http://apps.facebook.com/rss- graffiti/). Within Facebook, install the application, and then point it at the RSS feed of your site, which is of the form example.com/feed/rss2. The RSS Graffi ti application is confi gurable in terms of how frequently it checks the RSS feed for updates and the newsfeed header used to preface each update; most important, you can confi gure if you want to import the entire post or just an excerpt. If you send excerpts from WordPress to Facebook, then Facebook users will get a whiff of your content but will have to click through to your WordPress site to savor the whole content disk. If you’re concerned about splitting your audience, use excerpts; if you’re trying to grow your presence on multiple social networks, send entire posts upstream.
Buttons, Badges, or Both? As you can see, there are two equally important goals to sharing content. The fi rst is taking your content and spreading it out to the social networks, such as Facebook, Twitter, and Pinterest, which has been covered in this section so far. The second is linking to your own personal profi les on these sites from your own site, effectively showing the reader what’s on the other side of “Follow me on Twitter” or “Find us on Facebook” badges you might place in a WordPress widget in one of your sidebars.
c11.indd 292 12/6/12 1:32 AM Simple Social Networking Badges ❘ 293
Linking to your social networking profi les from your own site reinforces the idea of using your site as the hub. It validates your profi les as being truly yours and representative of your online voice. Connecting these profi les together is a double-edged sword because not only does it certify your profi les and solidify your online reputation, but it also drives readers from one site to your profi les or destination at another, potentially fragmenting your audience. Which direction your drive traffi c goes is a choice you will have to make, which is pretty much the same caution expressed at the out- set of this chapter. Validating your community profi les is a great thing if you are using your online presence for a professional endeavor, whether personally or for as a business entity. It’s advertising how involved you are and in what capacities. Affi rming your identities from your main site vets those other online presences like a trust system. This relieves any doubt your visitor may have, and you do not have to deal with Twitter “Verifi ed Accounts.” And you don’t have to change your name to @ theRealDavidDamstraHonest. You can link to your profi les pretty easily by editing the template fi les or using an HTML widget. In general, these links do not change very often, if at all. Nevertheless, some nice plugins handle all of the hard work for you.
For example, the Social Media Widget plugin (http://wordpress.org/ extend/plugins/social-media-widget/) by Brian Freytag supports many social media sites. Once installed, drag the widget into the appropriate sidebar in the control panel. Confi gure the widget using whichever social media URLs you are publicizing. Figure 11-2 shows an example of the widget. FIGURE 11-2: Social In addition to all of the built-in social networking sites, this plugin allows Media Widget for up to six arbitrarily customized ones and also the ability to use your own sidebar widget custom icons. It is a nice way to centralize all of your online presences into one easy-to-manage page. Many plugins can achieve similar results. Check them out and make your own evaluation.
SIMPLE SOCIAL NETWORKING BADGES
There are two different ways to integrate external social networking sites into your own site, and they have very different impacts on your content. You want to be able to distinguish between the two and to be able to decide when you need one over the other. The fi rst is what is called “simple social networking badges.” These are snapshots of your participation in an external site at a specifi c moment in time, and most can be auto-generated by the destination site (usually behind a button that prompts you to “Add a badge!”) Badge-based content is ephemeral and changes as frequently as you log activity on the external site. For example, these badges could be sidebar widgets showing your latest tweet or your current Facebook status. These simple social networking badges showcase your membership in other social sites, but they do not contribute to the content on your own site. They are more decorative than substantive, even if your participation on the other site is extensive. As mentioned previously, if you are much more active on Twitter, for example, than on updating your blog, then including your Twitter badge may cause some readers to migrate to your Twitter page to follow your online presence.
c11.indd 293 12/6/12 1:32 AM 294 ❘ CHAPTER 11 CONTENT AGGREGATION
The second possibility is actually to take the content, or a portion of it, from the external location and republish it on your WordPress site. This gives the content a life of its own, and on your own terms. Specifi cally, you are not relying on the third party to preserve your content, but are making your own copy in your own database, making it your personal responsibility to maintain. This is often called “owning your data.” Both the snapshot and republishing use cases have value, but you should recognize the difference in the permanence and longevity of the different approaches. This chapter covers both use cases. Using social networking badges creates a positive feedback loop around your WordPress site. Ideally, if you get people following you on Twitter or Facebook, they’re more likely to click through to your listed website to read your output in longer and larger form. People who read your site may also want to follow your shorter or unrelated updates on other sites; in both cases you’re relying on the network effort of “friends of friends” to drive interest in your content.
COLLECTING EXTERNAL CONTENT
You have weighed the pros and cons of integrating external content into your WordPress site. The next question is how are you going to do it? And which sites are you going to include? Basically, you can only include sites that have an API to permit the consumption of the data. That is not entirely true; you could code up a spider that logs into the remote site and harvests the information you want, but that would be pretty obscure and not fun to maintain long-term. For the purposes of this book, you are going to focus on exposed APIs. The basic method to integrate services is to read the API documentation and create a plugin or other function to consume and convert the information into something WordPress can use, such as a post. Because the underlying architecture of WordPress is PHP, you can use whatever PHP tricks you have up your sleeve and code a nice solution. For more information about plugin development, see Chapter 8. In truth, you do not even have to use PHP; you could use an intermediary language and interface with the WordPress table directly. For the sake of this section, you will focus on building a business site that will leverage social networks and other websites that provide functionality that can be embedded into your own site to add value or context. While you could build some these features yourself, the build-versus-buy decision becomes pretty easy on the open web, when essentially the cost is zero. Sure, there are business considerations about relying on third parties and including third-party code into your own business site, but at this time in the web’s development, users are more and more informed and aware that this is how websites work and they accept this functionality. Starting with WordPress 2.9, WordPress has included functionality for oEmbed. oEmbed is a means for one website to integrate a code snippet from another. The term “integrate” is used pretty loosely here because the HTML could be an element, but this methodology reduces the steps in including, for example, a YouTube video in your WordPress post. Check the WordPress codex for a list of services that are explicitly supported for oEmbed. c11.indd 294 12/6/12 1:32 AM Collecting External Content ❘ 295Integrating a YouTube Video Say you have a fabulous new marketing video that you need to include or promote on your WordPress website. Prior to WordPress 2.9, you had to browse to YouTube and grab the embed code snippet provided by YouTube and paste it into the code view of the Write Panel on your WordPress post or page. Honestly, it was not that terribly cumbersome — just a quick copy and paste for most of us. But average content administrators who are not as well versed in the intricacies of HTML often struggled. Because YouTube supports the oEmbed protocol, you can use this feature of WordPress to skip the entire HTML code snippet process and just use the video URL in your post. The URL should be on its own line and not hyperlinked, meaning you may have to undo the link with the WYSYWYG editor in the Write Panel for this to work (see Figure 11-3).FIGURE 11-3: WordPress write panel with YouTube URL (notice no hyperlink)When rendering this post to the browser, WordPress will recognize this URL as being oEmbeddable and will pull the content from YouTube to replace the URL in the content with the actual video, as shown in Figure 11-4. c11.indd 295 12/6/12 1:32 AM 296 ❘ CHAPTER 11 CONTENT AGGREGATIONFIGURE 11-4: WordPress post with YouTube video embeddedAs if by magic, this transformation takes place. If you inspect the HTML with your developer tools you will notice that WordPress is using an <iframe> HTML element to show the video from YouTube. This is ideal because that means the actual video content is being delivered to your visitor’s browser directly from YouTube’s servers, which are optimized for streaming media — they have built a business on it.Integrating Twitter Twitter became oEmbed-supported recently with WordPress 3.4. As with YouTube, you can include a Twitter conversation in a WordPress post or page by putting the URL on a single line and letting WordPress and oEmbed do the magic. For example, the WordPress post in Figure 11-5 produces the HTML output in Figure 11-6.FIGURE 11-5: WordPress write panel with Twitter URL (notice no hyperlink) c11.indd 296 12/6/12 1:32 AM Collecting External Content ❘ 297FIGURE 11-6: WordPress HTML output of Twitter oEmbedThe oEmbed functionality is great if you want to capture a single tweet or snapshot from a third- party site that supports it. But Twitter has been the poster child for open web service APIs. Is it still open? The Twitter API is well documented and easy to use once you overcome the authentication challenges. In addition, it has tons of features. All of this makes integrating your Twitter activities with your WordPress installation a breeze. As such, there are several things you can do with Twitter integration. For example, you can show your latest tweets in a sidebar widget; this is an example of a simple social media badge. You could archive each tweet as its own WordPress post, or get fancier and have daily or weekly archives. You could grab specifi c tweets and use them in your header to create a dynamic fi rst impression. Or fi nally, you could reverse the integration and automatically tweet every time you publish a new blog post.The Twitter Tools plugin (http://wordpress.org/extend/plugins/twitter-tools/) by Alex King does almost all of this. And it is all contained in one plugin with a simple control panel so you can pick and choose how you want to use it. Honestly, this plugin is a pain to set up, but it’s not the plugin’s fault; it’s related to how Twitter has changed access to the API. In the fi rst edition of this book, the Twitter API was wide open and integration was a breeze. You could leverage the Twitter API for countless examples because it was so simple and powerful. Now, Twitter is locking things down and integration is much more cumbersome. But once you get past the security API confi guration screens, this plugin has good functionality. For example, showing your latest tweets in the simple social networking sidebar widget is straightforward functionality with this plugin. First, install the plugin on your WordPress site and activate it. Using the new Twitter Tools dashboard, jump through Twitter’s security procedures to authorize your new connection. Twitter calls this an app and this is the cumbersome part, but if you follow the directions, it does work. Next, save your settings and jump over to the Widgets control panel. You will notice a new widget for Twitter Tools. This widget, by default, will show your last three tweets. Drag this widget to the appropriate sidebar for your theme to enable it. The benefi t of this method is that it is simple to implement; turn it on and it’s there. The downside is the transi- tive nature of this type of integration. You may generate some interest in people to follow you on Twitter, but it does not provide lasting content for your personal site. c11.indd 297 12/6/12 1:32 AM 298 ❘ CHAPTER 11 CONTENT AGGREGATIONTwitter Tools can also convert each individual tweet into a post. Depending on how you use Twitter, this can be a nice way to back up or archive your tweets on your own site. For example, if you use Twitter to create notes to yourself, having WordPress convert these to posts will give you the simplicity of Twitter, but then include the power of the structured content in WordPress. An alternative approach is to publish your tweets as you would asides — although, at this point, you can’t use the post format talked about in Chapter 9 because the plugin does not support it — intermingled around your regular journal or news posts. Think of asides in the same context as comments you make in the course of conversation that aren’t related to the main topic at hand. In this case, because they are originating from Twitter, they would be single-line posts, which would be ideal for the asides post format if it were available. Simply take the tweets from Twitter and create new posts in a special category. Your theme has to handle this special logic to create the right “asides” feel — shown in a sidebar, or highlighted, to differentiate them from the main narrative of your blog posts. Once you have the tweets making new posts, this could be as simple as using the Twenty Eleven theme discussed in Chapter 9 and some specially crafted CSS to make it look like the aside post format. If you’re publishing each tweet to its own individual post, Twitter Tools also has the capability to create daily or weekly digests. This is particularly interesting when you use Twitter to capture moments of your day through tweets. The challenge with Twitter is how easy it is to use, and yet, because of the size restriction, you are forced to keep your posts short — hence microblogging. In this case, you are telling the daily story of your life in a series of small takes. Allowing WordPress to import them creates another form of the same narrative. It is no different from writing an entire post entry and publishing it, except this approach self-assembles posts from the microblogging format used by Twitter. Another feature of Twitter Tools enables you to reverse the integration — that is, tweet when you publish a new post. This feature has to be explicitly enabled in the Twitter Tools dashboard. Once turned on, Twitter Tools will automatically tweet on your behalf that a new post has been published and will include a link to your article. For some people, this is a nice alternative to RSS syndication, which you will look at later in the chapter.Google Maps Google Maps, or really any mapping service, is a commonly requested item. If, for any reason, you want clients to actually visit your place of business, or want them to attend a certain event, you need to provide directions. Online mapping and direction services such as Google Maps are ubiquitous for this now. It is hard to remember how you found your way around town before, but at the same time, you now have the social benefi t of location-aware services. Anyway, you want to add a map to your site. Google provides a nice mechanism to simply embed a map in your site using its tools. You can fi nd this in the top right of the Google Maps page. Copy the code and paste it into your WordPress post or page. It is that simple and it works. Google Maps seems like a prime candidate for oEmbed functionality, but it is not supported. So for now, going back to the old-school copy-and-paste is the most straightforward way to embed a single map into your WordPress website. c11.indd 298 12/6/12 1:32 AM Collecting External Content ❘ 299Like Twitter, Google Maps has an extensive API and there are many WordPress plugins that offer different map features or functionality, such as placing multiple markers on the same map, embed- ding multiple maps into the same post, or providing an HTML user interface for your site administration. Depending on your or your clients’ needs, one of these may fi t the bill.Integrating Facebook Facebook is the new walled garden of online communities. Various roads exist into Facebook, but very few to get data out. This makes integrating your WordPress site with Facebook somewhat more of a challenge. Until recently, Automattic and Facebook worked together to create a plugin specifi - cally for WordPress and Facebook to integrate together, available online at http://wordpress. org/extend/plugins/facebook/. This plugin aims to deeply integrate your Facebook network with your WordPress site. Similar to Twitter, you have to register a Facebook App with Facebook to use this plugin. This can be a cumbersome process to get the integration working. There was a lot of trouble with Facebook’s CAPTCHAS, but this seems like the way things are headed in order to use third-party APIs. Again, follow the directions on the WordPress plugin page carefully and it works. Once the authentication and setup rigmarole is complete, you will have a control panel to confi gure how much integration you want to enable. There are several components to choose from and each has some display confi guration options. One of the more interesting components of this plugin is the ability for the comments to be aggregated as Facebook comments. Facebook is currently the big gorilla of social networks. Being the biggest and most popular means that people complain about it and stop using it, but the truth is, being so popular means that that is where the audience is. Integrating your site with Facebook is a trade-off between reaching potential viewers and adhering to their terms and practices. Generic XML Data Now that you have looked at some of the biggest and most common integration points, let’s take a look at a simple example for integrating a generic XML data source into your WordPress site. This could be any generic content source or custom source you might have. In this example, you will look at XML, but it could be JSON or any other agreed upon fi le format. What you’ll do here is take an XML formatted feed and consume it using PHP code. In this example, you are using an external data source to provide some confi guration and content information to your WordPress site. This might be the case where you are using WordPress to create an external marketing website for your client, but they are using an internal application to actually manage the business. That is, the client uses their internal application to set some content or criteria, and you have created an interface to broadcast that criteria via XML. Your WordPress site picks up that XML data and uses it to customize the WordPress site. This makes it so the business has to manage data in one place only. This example is going to be a little contrived. As with most things, there are many ways to accomplish this and depending on your circumstances, this may not be the easiest or most straightforward. You might even think: Why not just use the WordPress content management functionality to manage this data? While potentially unrealistic, this example showcases integration principles that can c11.indd 299 12/6/12 1:32 AM 300 ❘ CHAPTER 11 CONTENT AGGREGATION be used and are used in real-life situations. This example is adapted and simplifi ed from an existing process used in production. Pretend that you just signed an Umbrella retailer as a new client. The CEO of your client company is adamant that, to keep the website looking fresh, he wants to match the background color of the website to the color of the week. The color of the week is also the color of the umbrella that is on sale this week. The CEO picks the color of the week on Mondays and keys it into the point-of-sale system so all the sales people know which color is on sale. The CEO does not want to have to worry about the website, but wants the color to match. As mentioned previously, there are many ways to accomplish this. But when you talked to the company’s system administrator, he mentioned that the color of the week was exposed in a REST API. Again, while the example is constrained and the context is carefully set up for this example, increasingly resource content and real-time data are exposed via RESTful APIs, and knowing how to extract data from those endpoints will give you a richer set of external data sources with which to customize WordPress. This chapter is about aggregating and consuming content, so this is the perfect opportunity to leverage your newfound knowledge and take the data feed and modify the website on the fl y. Here is your plan of attack. First, you are going to create a function in your theme’s functions.php fi le that will retrieve the API data, parse it, and hand it off to the theme rendering. This code could just as easily be a plugin or even included in the header.php template fi le. For this example, it just needs to happen on every page load. (This is not ideal, so more on this in the next section.)In the functions.php fi le, you will create a new function calledget_color_of_the_week() , and the code might look something like this: function get_color_of_the_week() { $feed = file_get_contents('whatever URL'); if ($feed) { $xml = simplexml_object($feed); $color = $xml->color; } else { $color="white"; } echo $color; }This function uses the PHP function file_get_contents() to get the XML from the point of sales’ exposed API. The data is then converted to an XML object, although you could do the same thing with JSON or other data formats. Then the variable for the color is set based on the content of the XML payload. It’s pretty straightforward. Next you need to use this color as the background color of your HTML <body> element. In your header.php template, you might do the following:<body <?php body_class(); ?> style="background-color: <?php echo get_color_of_the_week();?>" > This will use an inline style to override any CSS from the style sheet. This code also has to happen inline because you are using PHP to echo the contents of the XML. This methodology is similar to the way the built-in WordPress Theme Customizer discussed in Chapter 9 works. c11.indd 300 12/6/12 1:32 AM Collecting External Content ❘ 301This method will only work if the CEO types in something that is recognized as an HTML color, whether a hex code such as #fffff or a named color such as Papaya Whip. Certainly, the preceding code could use some error checking and handling. Think beyond this simplistic example. This same principle could be applied to any number of unique possibilities, including site customization from a third-party system, as shown here. But it could also be content that is parsed and handled in a specifi c format, perhaps loan rates or other business subject matter. As you have probably put together, the preceding example is not very effi cient. Every request to every page makes a call to the REST API to fi nd the background color. Depending on network con- gestion or many other factors, this could be a time-consuming prospect that dramatically affects the load time of your site. Time to load is a large component of the user experience, as discussed later in Chapter 12. In addition, because this information changes only once a week, why ask for it on every page request? Why not remember it, or cache it for the week. This is where WordPress transients come in.Transients Transients are very similar to the WordPress Options feature discussed with plugins in Chapter 8. The major difference is that transients include an expiry time. By their very nature, they are only available for a defi ned period of time — you can think of this as though they are self-refreshing or self-updating. This makes them ideal for caching “expensive” data for a defi ned period of time. What is expensive? Expensive data is data that takes longer to retrieve or calculate. In the previous section, and in the upcoming example, you will look at how accessing a third-party API could be considered expensive, depending on network latency, most importantly you do not want your site rendering to have to wait for a third-party access. However, it could also be a computationally intense query or calculation — for example, generating a complex menu for your site, or a query that spans a whole network of sites on MultiSite. What you are doing here is caching some data for quick retrieval, which is to say, having the information at WordPress’s fi ngertips. What is a defi ned period of time? Here is the rub: you have to balance having data readily available but without it becoming stale. In the previous section, you manufactured a situation where the time the data remains current is clearly defi ned: one week. In the real world, you may never know how often the data gets updated or needs to be refreshed. In fact, to further complicate this, there could be many levels of caching on your WordPress site. Caching is covered in greater depth in Chapter 13, but just consider the interactions between the various places in which data can be cached. The source of your data might have caching, or be delayed in presenting the internal information to the API for you to consume. Your transient data has a caching expiration on it and your WordPress HTML rendering might have a caching mechanism. Your visitor has browser caching and possibly even network-level proxy caching. This means that there are many factors that could affect the pipeline of getting data from an offsite source to your visitor’s browser. This can be a big, and sometimes frustrating, factor when developing and testing your integration but it also affects the time period you select for storing your transient data. So what is the defi ned period of time? It depends. It depends on your data, your tolerance for stale data or requirements for up-to-date information, and the load on your site. In the previous section, c11.indd 301 12/6/12 1:32 AM 302 ❘ CHAPTER 11 CONTENT AGGREGATION where you did not want to access the API on every page load, this did provide the freshest, most current data. But it also put a load time restraint on your theme, and also an access load on the API server. Transients are designed to reduce or remove both of these conditions. As the developer, you have to set the expiration time to balance expectations of current data while reducing the access load on the third-party service. Your goal is to fi nd the longest time period during which old or stale data will not produce an adverse user experience. To borrow from the world of non-SQL databases, you need to determine how you’ll make the data eventually consistent, without introducing errors in user action due to inconsistent, cached data. Use the same example as the previous section, but introduce transients to locally cache the information. In your functions.php fi le, you will modify the function to include the transient storage. The fi rst thing to do is check if you already have any existing, non-expired data. If your transient data does not exist, or is expired, the get_transient() function will return false. if (($color = get_transient('color_of_the_week')) === false) {If this check returns false, that means you need to access the API and get new data. Again, this caching is separate from any HTML- or PHP-level caching your site is performing. This check is directly related to this specifi c piece of information. The following is the same code as the previous example:$feed = file_get_contents('whatever URL'); if ($feed) { $xml = simplexml_object($feed); $color = $xml->color;Now that you have the updated data, you need to store it in the transient and set the expiration time. This essentially works the same as the WordPress options API with the added expiration parameter. set_transient('color_of_the_week', $color, 60*60*24*7);For readability, you are presenting the expiration time as a calculation. WordPress expects this parameter in seconds. In your example, you want to hold this data for one week, so the calculation is 60 seconds times 60 minutes times 24 hours times 7 days giving us a week’s worth of seconds. You could also push 604,800 as the second parameter, but often it is easier to read the intent of the time with the calculation. Putting it all together, the new function with transient caching might look like this: function get_color_of_the_week() { if (($color = get_transient('color_of_the_week')) === false) { $feed = file_get_contents('whatever URL'); if ($feed) { $xml = simplexml_object($feed); $color = $xml->color; } else { $color="white"; c11.indd 302 12/6/12 1:32 AM Advertising ❘ 303} set_transient('color_of_the_week', $color, 60*60*24*7); } echo $color; }Finally, to use this color in your HTML, the changes are exactly the same as in the previous section. All of the new caching magic is encapsulated in the function from the previous code snippet. Your header.php template changes should look like this:<body <?php body_class(); ?> style="background-color: <?php echo get_color_of_the_week();?>" > As you can see, by adding two simple lines of code to your custom feature, you have now added caching functionality to reduce load time on your site, removed reliance on a third-party connection (during the caching period) and decreased the access load on that third-party server. It’s a pretty simple process and can drastically affect your site performance for data that does not have to be immediately current.ADVERTISINGWhen using your website to sell a product or service, or gain potential customers for your business, your WordPress installation is more overhead than profi t center. On the other hand, personal jour- nals or blogs with large readerships often drive nontrivial advertising rates, picking up the online equivalent of local or national newspaper display ads. In this section, you look at various aspects of the money game, from confi guring ad boxes to becoming an affi liate merchant site. If you’re wondering what this section is doing in the middle of a content aggregation discussion, it’s here because advertising is a syndication issue. You’re either taking someone else’s idea of an attractive, keyword-specifi c ad and placing it in your content stream, or you are putting your own ads into someone else’s display slots. Just as it is important to consider audience fragmentation and multiple or parallel channels for your readers, you also need to think about the impact of your site’s display advertisement on the visual and user experiences. Monetizing Your Site There are a number of ways to monetize your WordPress site: display ads from one of the larger online advertising agencies such as Google become an affi liate of an online merchant such as <a href="/tags/Amazon_(company)/" rel="tag">Amazon</a> that offers commissions on click-throughs that result in product sales, or sell specifi c sponsorship or banner space on your site to an interested party. When you go down the commercial route, however, you are also making an explicit decision to cede some of the design and display value of your site over to a third party. For a personal site, or a blogger, this is usually fi ne. For a commercial site, this is probably a non-starter. There is also that vast middle ground where your personal hobby is really a business — think of comic strip sites and larger scale personal op-ed sites. Passive monetization of your content is nice, and some truly popular websites do throw off enough advertising revenue to fund small companies, but for the average blogger, advertising is going to c11.indd 303 12/6/12 1:32 AM 304 ❘ CHAPTER 11 CONTENT AGGREGATION be more about catching an occasional click-through. It’s critical to have reasonable expectations of how much advertising revenue your blog can generate, because you’re trading off aesthetics and display space for advertisement placements, with little control over the products and graphics styles represented. Advertising monetization ranges from the pay-per-click model, where you get paid each time a viewer clicks on a displayed ad, to the pay-per-view or pay-per-day model, where you earn income for simply displaying the ad or placing an ad on your site for some specifi ed time period. Google AdSense fi ts the fi rst model, where Google’s ad syndication service establishes a price per click based on keywords and content, and then matches available advertisers to available slots based on Google’s defi ned market pricing and advertiser budgets. Project Wonderful is an example of the pay- per-day model, where you offer predefi ned ad boxes to potential advertisers, and Project Wonderful runs a continuous auction for each day of display. You get the same income whether or not anyone clicks on the ads. In all models, the value of advertising slots offered on your WordPress site is proportional to the popularity of your site and the probability of a view or click-through. If you do not have a variety of content that’s regularly updated, your ads will tend to cluster in the equivalent of late-night local cable television commercials. Similarly, if the thought of a weight-loss ad sitting under your post discussing the “fat tone” of a jazz guitarist’s solo offends your sensibilities or detracts from the serious- ness of your musical musings, consider passive monetization of your site using an affi liate or referral program such as Amazon Associates that pays you a fee for each referred purchaser. Furthermore, with ad networks gaining more insight into where visitors browse and what they are shopping for, ads are more and more tailored to the specifi c visitor. This means that the ads you see are not the ads that someone else sees. Compounding these issues is the path users take to fi nd your content; advertising is carried on your hosted WordPress site, but not in content republished through Facebook or aggregated on other sites. If your site is read through an RSS feed, make sure you consider choosing an advertising manager that places ads in feeds as well as in the generated HTML for your content.Setting Up Advertising Placing advertising on your site is no different than laying out a print page with a mix of editorial and commercial content: decide how many ads you want, where they are going to be placed, and what potential content confl icts you want to avoid. This is as much a design as a technical process, because you have to pay attention to the eventual page presentation and tone of the content when displayed with advertisements.Using Advertising Plugins Before running ads on your site, you need to create an account with one of the popular ad syndication services. Generally, this means that you have to create a login, describe your site, demonstrate some minimum competence in terms of content, and provide payment information. In return, you get an advertising client identifi er, and usually a slot (or ad) identifi er. If you’re using Google AdSense, for example, you can create multiple channels for your advertising slots, perhaps tying different channels to different categories or parts of your site, or using one channel for each of several different sites you manage. The client identifi er is tied to you as a payment entity; the channels c11.indd 304 12/6/12 1:32 AM Advertising ❘ 305 describe different display destinations for ads and may be wildly different in terms of their content, size, shape, and going click-through rates. There are many different WordPress plugins for managing your advertising relationships and their impact on your site. Finding the right one for you and your ad network is left as an exercise for the reader. Just make sure you read the disclaimers carefully. Some plugins will show several of your ads, and then interject one from their own ad network to offset their development costs. Make sure you know what you are signing up for. Usually after installing the plugin, confi guration is as simple as choosing the ad service, copying your account and slot information into the control panel, and choosing the display specifi cs to gov- ern the size and shape of ad boxes. If you want to exert explicit control over what is being advertised on your site, rather than handing that option off to an ad syndication network, you can take over the advertising management and manage it manually. There are some plugins to help with this also because with WordPress there is a plugin for everything. If you want to set up site sponsorships, where someone pays you for a spot that shows up in the header, footer, or sidebar, or you want to sell simple display ads that rotate through the site using your own rate card and payment schedule, doing it manually gives you the most control over the insertion of ads into your site.Manual Advertising Placement The advertising plugins work very well if you want to attach ads to each post or have them show up in the header or footer of every page. The plugin architecture covered in Chapter 8 handles fi ltering of post code to replace the smart codes with a JavaScript template to call your advertising service, or inserts the appropriate script in the theme’s content fi les. If you’d like fi ner grain control over ad placement, such as more tightly integrating the ads into some theme elements, then you’ll need to hand-edit the appropriate fi les and insert the advertising script code. You won’t go through every permutation of editing theme fi les to insert ad boxes, as this effort is a derivative of the theme creation discussion in Chapter 9. In general, if you’re adding an advertising box to your header or footer, then it’s going to go just below the last <div> in the fi le so as not to interfere with other theme elements. In a sidebar, the ad box should be a separate list element, with the ad box code surrounded by <li> and </li> HTML tags. The manual insertion process is not much different than adding a Facebook badge or Twitter icon to your sidebar, as the ad box code is automatically generated by your advertising manager site. For example, if you are using Google AdSense, the control and confi guration pages for AdSense enable you to choose the shape of the ad (rectangular or square), the size of the display box, and the color scheme used. The fi nal step in the ad confi guration shows you a small chunk of JavaScript that you copy and paste into your WordPress fi le. In the example code snippet, the Google ad client and ad slot identifi ers have been blocked out, but you can see the relative simplicity of the ad display process. The script calls Google’s ad syndication engine with information about the destination (your ad client information), the size, and a slot identifi er that Google uses to account for ad displays in terms of different “channels” that you set up within their confi guration system:<script type="text/javascript"> </script> <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> </script> Note that the variables defi ned in the JavaScript are exactly the same values you would have entered in an AdSense plugin. The other somewhat obvious point is that every time you display a Google ad, you’re calling Google’s syndication service to decide which ad to insert and waiting for it to return the image and text. This has a nominal impact on your site’s perceived performance, unless Google is particularly taxed and your site display is slowed by the advertising generation. Hand-editing and insertion of ad boxes from other services is equally simple. Project Wonderful’s JavaScript code is even more compact. Where you put the ads and their shape and style are codependent. If you are going to add a stack of ad boxes to your sidebar, then a single column of ad boxes with multiple rows is best; ensure that the width of the ads fi ts within the sidebar width used by your theme. Opt for a header or footer approach and a single row of multiple ad slots, or a short multi-row matrix, whichever fi ts best. The size of your advertising box also governs what type of ads fi t within it: leaderboard ads that span the entire width of the display page won’t work in a sidebar, and are least visually diffi cult when there’s only one per ad box. Project Wonderful lets you defi ne multiple ad boxes per site, so if you want to mix and match ads of different geometries, consider wide, single-row boxes for headers and footers and the skyscraper or tall matrix approach for stacks of buttons or square ads in sidebars or under blog posts.Dealing with Confl ict Confl ict between commercial and editorial content probably dates back to the fi rst newspaper that carried advertising. Within the context of this book, you’ll only look at two potential types of confl icts: ads you don’t want in your space, and advertising platforms that don’t want others in their space. Undesirable ads run the gamut from unrelated products to things that you fi nd offensive. Part of the issue is how the advertising managers decide to match ad campaigns to available advertising slots: keywords and context from the content itself are matched against those keywords that the ad campaign chooses. If you fi nd yourself writing about food, eating, and the resulting weight gain, perhaps in an off-hand manner, don’t be surprised if the weight loss ads start showing up under your posts. Perhaps your best defense here is a good offense: write regularly, keep your site dynamic and updated, and use tags and the search engine optimization techniques discussed in Chapter 12 to best present your content to advertising managers. All media vehicles that carry advertising have their own standards of business conduct, such as not running two commercials for competing businesses in the same advertising break. Online advertising services impose their own terms of service on their channels, typically limiting the number of ads that can be placed per page, the types of pages in which ads can appear (not in e-mail, or not on pages that encourage viewers to click away in a thinly veiled click fraud scheme). When you use c11.indd 306 12/6/12 1:32 AM Privacy and History ❘ 307Google AdSense, you are free to display other ads on your site, provided they are differentiated in color and style to avoid confusion with Google’s displayed ads. On the Google AdSense confi guration page, pick a color palette for those ads that is distinct from that used by your theme, and then whatever ad slots your theme controls will have distinct borders and backgrounds. If your theme has a widget or slot earmarked for advertising, use that for self-hosted, sponsorship, or rotating banner type ads, and let Google AdSense manage the per-post or per-page boxes, being careful not to mix different advertising platforms in the same part of your display page where they could be confused. Advertising has been a part of public visual media since the dawn of television and highway bill- boards. As a site administrator, developer, and content creator, you need to decide how and where you want to commercialize your work, and if the aesthetic and editorial efforts are worth the potential fi nancial return.PRIVACY AND HISTORYWhether you are creating a business site or a personal site, aggregating your various online interactions into your WordPress site creates the benefi t of one true source of your online presence. This makes it easier for your clients, potential clients, family, or random admirers to track what is currently happening with you. However, you might not want to cross the streams, so to speak, for a number of reasons. The obvious reason is the complete opposite of the reasons why you would want to aggregate all your social media content — privacy. The main reason for bringing it all together is for discoverability and getting noticed. What makes you discoverable, however, is putting it all out there. Sometimes, for your personal information, this is not what you want. Privacy should be a concern for anyone publishing information on the Internet. Google caches anything it can fi nd; so does the <a href="/tags/Internet_Archive/" rel="tag">Internet Archive</a>. There is not anything nefarious about that, but just be aware that once it is out there and discoverable, it is potentially always out there. There is no “Are you sure?” button to click. To quote an old Usenet warning:This program posts news to thousands of machines throughout the entire civilized world. Your message will cost the net hundreds if not thousands of dollars to send everywhere. Please be sure you know what you are doing. Are you absolutely sure that you want to do this?While the actual fi nancial impact may not be true anymore, if it ever was, you can understand that the concern about “no going back” has been around a long time on the Internet. The short story is to take a deep breath before you publish something into the ether, because you do not know its life span. Once you say it on the Internet, it is said forever. We don’t yet know how kids are going to react when they realize their entire life from birth to this afternoon has been permanently documented on Twitter, Facebook, and personal websites. Long term, it could potentially be far more embarrassing than that picture of you in the bathtub as a baby. When putting it all out there, you have to be careful. You hear stories about employees being fi red because of Facebook — they call in sick and then post stories on their Facebook page about playing c11.indd 307 12/6/12 1:32 AM 308 ❘ CHAPTER 11 CONTENT AGGREGATION hooky and fooling the boss. Posting inappropriate pictures on Flickr can have a lasting effect on your reputation. Within fi ve minutes of interviewing potential new employees and reading their resumes, many human resources specialists are on search engines and social media sites looking for information about them. Often, you can fi nd details that you are not allowed to ask about in a traditional interview. It is an augmented background check of sorts. For better or worse, aggregating all this content onto your WordPress sites makes it all public and easily accessible, and a well-managed online persona can enhance your business brand or personal reputation. Finally, collecting all of your online information in a central location can enhance the user experience and build trust at the fi rst impression.SUMMARYThis chapter covered a range of topics focused on empowering your WordPress site to participate more with other aspects of the Internet, including pushing your content to other sources and focusing on bringing external content into you site. Third-party content could be actual copy or comments but could also be services that enhance your client experience or confi guration information for your site. Third-party content was also presented as advertising that might help monetize your site. This chapter also discussed some of the implications of fracturing your audience amongst the various locations on the web. The next chapter will focus on how you take your content and craft a meaningful User Experience. c11.indd 308 12/6/12 1:32 AM 12 Crafting a User ExperienceWHAT’S IN THIS CHAPTER?➤ Understanding the principles of the user experience ➤ Learning the benefi ts of usability and usability testing ➤ Recognizing how to optimize your site for search engines ➤ Improving the built-in WordPress searchThe last few chapters have been about creating and presenting your great content to the user. In truth, those chapters are really about your own goals — how you want the site to look and function and what content you are presenting. But it is not all about you. What about the visitors to your site? This is where the user’s experience is a factor. Up to this point, the focus has been on how to create a site and manage its content. Now the question is — is the site going to attract and retain viewers (users) because of the mechanics and decisions you have put in place? Because you are dealing with people and their unique perceptions, it is an entirely nondeterministic exercise. That is, beauty is in the eye of the beholder. The user experience really involves more than what an actual person sitting at a browser in Middle America thinks. Indirectly, web spiders, search engines, and service consumers such as RSS readers are also your users. Your site needs to be designed and structured so that all classes of users benefi t and have a great experience.USER EXPERIENCE PRINCIPLESUser experience is a topic that is open to interpretation; everyone sees it a little differently. But some good guidelines are available. Some of these guidelines are common sense, or seem to be. They all strive to establish a balance between what is aesthetically pleasing but also practical. c12.indd 309 12/6/12 1:23 AM 310 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCEThese are not hard-and-fast decrees that must be followed. Humans are fi ckle and these guidelines need to fl ex to meet their needs. Here are some basic questions to ask: ➤ Does my site have a consistent look? ➤ Is the design helpful or hurtful? ➤ Is my content easy to fi nd and access? ➤ Is my content well structured? ➤ Is my site reasonably quick to load?This list itemizes the pillars of the user experience. How you choose to use them, or in what combination, is really what this chapter is about. The following sections delve into these topics for a little more clarity.Consistent Navigation This is almost a no-brainer these days; it is diffi cult to not have a consistent look and feel with WordPress themes. You want your visitors to be aware that they are consistently using your site, independently of the path taken to get there. That means having a coherent look and feel to your site — such as a masthead and dependable global navigation. That does not mean that different sections cannot have their own fl air, but it needs to be coherent. It will be very disorienting for a visitor to read some of your content on one page and then click through to the next page with a totally different look and feel to it. Visitors will think they have left your site and you will not get credit for the great content you have created. Likewise, each page in your site should have a dependable global navigation. Dependable means it does not change and does not move. Visitors should be able to explore your content without fear of getting lost. It may sound silly to a technologist like you, but the average user has a different relationship with technology. This global navigation is a safety line for your visitors to get back to where they came from. Good global navigation also tells visitors where they are in the site. Specifi cally, setting an “active” item in the menu and making it clear that it is lit up, or somehow distinguished from the rest of the global navigation. This enables a visitor to glance at the navigation and immediately see where he is in your site with respect to the other sections or pages. The built-in menu system in WordPress does this automatically; you will automatically receive a current_menu_item class in your currently active menu items like so (this is the rendered HTML):<li id="menu-item-44" class="menu-item menu-item-type-post_type menu-item-object-page current-menu-item page_item page-item-42 current_page_item menu-item-44"> c12.indd 310 12/6/12 1:23 AM User Experience Principles ❘ 311<a title="Register Me" href="/register-me/"> Register Me </a> </li>Alternatively, if you are creating navigation yourself using WordPress’s built-in is_page() function, you can achieve the same result (this is the PHP code in the template fi le):<li class="benefits <?php if(is_page('benefits')) { echo "current_menu_item";}?>"> <a title="benefits" href="/benefits/"> Benefits </a> </li>In both cases, some nice CSS on the current_menu_item class would differentiate this menu item from the rest. We (the authors) are fi rm believers in the user feedback functions of the anchor element. First, mousing over the element should provide some sort of feedback beyond switching the cursor to a hand. Usually, this means a highlight or darkening of the font, background, or border. Second, the currently active navigation section should be similarly delineated, but different. These two tenets, when taken together, create a nice global navigation that visually presents a multitude of information on where the visitor is in relation to the rest of the site and where he can go to read more. Some sample CSS adapted from the Twenty Eleven theme might be:#access li:hover > a, #access ul ul :hover > a, #access a:focus { background: #5B84BA; }#access .current-menu-item > a, #access .current-menu-ancestor > a, #access .current_page_item > a, #access .current_page_ancestor > a { font-weight: bold; background: #5B84BA; color: #efefef; }This works in Chrome, Firefox, and Internet Explorer 6 through 9. In Figure 12-1, you can see how this plays out in the web browser. If you browsed this site in real life, you would see that the global navigation across the top is in the same place on each and every page of this test website. You will also notice that this screenshot is of the Child Page of the Sample Page menu item, and that navigation item is visibly different from the other menu items to indicate that it is the active page, and also the active top-level navigation item. c12.indd 311 12/6/12 1:23 AM 312 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCEFIGURE 12-1: Active navigationNotice that it is referred to as global navigation. That does not mean that every page in your site has to be listed in the main menu. It can be, but it does not have to be. Sections can have a local navigation block once you are inside them, but the main sections should be accessible via the main menu. This is what makes navigation dependable. It reinforces what the visitor can expect on your site and the methods used to navigate it. A consistent style and dependable navigation comfort your visitor and reinforce the validity of your content.Visual Design Elements Specifi cally, are the visual assets of your site helpful or distracting to the user? Does the theme reinforce the persona you are portraying with your content or detract from it? This is another one of those topics that are open to personal interpretation. Photos and colors trigger differing subjective responses from different people, but the overall impression of your site should match the general content. For example, a business site should not have a bubble-gum pink theme if it wants to be taken seriously — unless, of course, the site is selling toys or bubble gum. At the other extreme, there has recently been a bit of backlash against the use of pink to denote sites or content addressing women’s health issues; overuse degrades its impact and importance if blindly applied. Visual design should refl ect the brand and brand values you are trying to develop with your WordPress site. c12.indd 312 12/6/12 1:23 AM User Experience Principles ❘ 313Colors evoke different feelings. Blue instills trust, which is why it is so prevalent in business and fi nancial logos. Orange suggests new technology and is often used in the telecom industry. Color and branding is a whole topic unto itself, but just consider that pink ponies may not be the way to market your bank, and skulls and crossbones may not be the way to market your children’s furniture site. This topic is pretty diffi cult to gauge. It is a very emotional topic and often marketing takes over rather than commonsense. For example, it is likely that many of you have worked for clients who were absolutely certain that each new addition to the index page will be the most important thing on the page. That meant that every design element was oversized and blinking, causing the whole page to become nausea inducing. Sort of along the same lines as laundry detergent: if every brand is ultra-new-super-improved, are they not really all the same again? One design theory that that works well when working up a new mockup is to toil away at the composition. Build up layers of elements working toward the end goal. Once you are happy with what you think could be the fi nal mockup, remove an element. Kick it back one rung and use that. This is a variation on the less-is-more approach. Take, for example, the mockup being created in Adobe Photoshop in Figure 12-2. You will notice in the Layers palette on the right side that all the components that make up the mockup are broken into individual layer groups. During the development of this mockup, each graphic element was composed using this method, which means that you can easily move and change them without interfering with other layers. You will also notice that a couple of the layer groups are currently turned off: The little eyeball icon is not there next to them. When creating this mockup, both of the graphic elements in those layers were tried and deemed to be too much. Turning them off, kicking it back a notch, created a stronger layout.FIGURE 12-2: Mockup being created in Photoshop c12.indd 313 12/6/12 1:23 AM 314 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCEMaking Content Easy to Find With a successful site, you will reach a point where you have a substantial body of content. Often, the visitor to your site does not categorize or organize content mentally in exactly the same manner as you do. Therefore, there should be multiple paths to get to all content in your site. This increases the likelihood that visitors will be able to fi nd what they are looking for. This is also an excellent reason for having categories, tags, and calendar-based archives templates. Having these templates addresses three popular ways in which people remember where something was. They also serve as a way to drive more content interaction and consumption, exposing your thoughts (as the creator) on content sorting. WordPress assists in this strategy right out of the box. First and foremost, your site should have a dependable global navigation, as mentioned previously. WordPress encourages this with its native structure, but how you actually build and organize the navigation is up to you. Second, WordPress does come with a built-in search functionality. Although it can be improved, as discussed later in this chapter, some search is better than no search. Tagging your content helps with search. Third, WordPress offers many alternative views of the content. Either with special templates or by simply using the default index template fi le (see Chapter 9, “Theme Development,” for more information on template fi les), WordPress can offer up your content by date, category, title, or author, or through several other variations. Creative use of these templates and other custom loops offers another vector into your content. The catch here is that this method also serves duplicate content, which the search engines discourage, but that is covered later in this chapter. Fourth, many plugins are available for related posts. Adding a related posts list to the bottom of a post is another method for providing a deeper dive into your content. This is particularly effective if you have already piqued the interest of your reader with one set of content. Offering similar content is a great idea, and it is a way to provide more information on the subject that can be useful to your visitor.Site Load Times Back when dial-up was the most prevalent means of connection, web developers were extremely conscientious about the weight of the page and how long it took to load. But as broadband access has increased, developers have become lax about load times when updating existing sites. CSS fi les have bloomed as new selectors and styles are added rather than merged with existing styles. AJAX and JavaScript libraries have been included, sometimes more than one JavaScript library, just to achieve neat-o gee-whiz effects. iFrames, web services, and other third-party components all add to the bloat of an HTML document. Multiple database queries to gather information slow down the page on the server side. In addition, elaborate new designs require more CSS and images and other effects, which adds to the bandwidth infl ation. This is a problem for both new greenfi eld development and with the maintenance of legacy designs. Is the time to load still a factor to consider? It should be. The fact that the access speeds are faster does not mean you should ignore optimizations in the code. However, never optimize too early in the process. Premature optimization slows down the development and deployment of your site. This is a delicate balance between getting things done and out the door and optimizing them c12.indd 314 12/6/12 1:23 AM User Experience Principles ❘ 315 so the launch is successful. Page load times should be a consideration when developing your site. A nicely optimized site loads much quicker than one that was put together by someone who does not understand the implications. This can be a complex issue: think about all the aspects that affect load times of your website. There are the obvious ones that you should be familiar with, including the quantity and sizes of images, the number of JavaScript libraries being used, and to what effect those JavaScript libraries are being used. Consider also your integrations with third-party sites, such as using a few too many Facebook badges with Status and Like updates, or multiple hotlinked images from image hosting sites. What happens when these remote locations are slow to respond, or worse, do not respond at all? Does your site’s response time suffer because of something outside your control? Think about the tree of performance dependencies that you create by referencing other sites. That does not mean that you shouldn’t use them at all, but that you should recognize how they can affect your own site’s performance. Firebug continues to be an excellent tool for working through optimizations and network bandwidth on your site. Google Chrome’s Developer Tools is also a very popular choice. In addition, Yahoo! and Google each have add-ons for Firebug and Chrome Developer tools to help improve your page speed: YSlow (http://developer.yahoo.com/yslow/) and Page Speed (http://code .google.com/speed/page-speed/), respectively. A caveat with YSlow and Page Speed is that they are provided by Internet power houses. These sites likely see more traffi c in an hour than you see all year. The problems and speed issues that they need to address are not the same types of issues that you need to address. YSlow always recommends a Content Delivery Network (CDN). Sure, a CDN distributes your assets across a geographically diverse set of servers to increase reliability and reduce latency, but does your site really need this? Do you really need to incur the costs? It is a developer choice, but in short, just remember that your site is probably not on the same scale as Yahoo! or Google. You need to pick and choose your battles in the area of site load times. Here’s a quick checklist of things to consider, starting with the low-hanging fruit: ➤ Optimize your graphics and pick the right DPI, color depth, and format. Don’t forget about higher DPI Apple and other mobile devices. ➤ Standardize your JavaScript library and use only one. Measure the benefi ts of packing and minifying your JavaScript and CSS. Those efforts may not improve page load times. ➤ Evaluate the number of external references made, whether hotlinking an image or including a Facebook badge with a status update. Consider using transients, as discussed in Chapter 11. ➤ Be sensitive to MySQL database performance on your hosting site. Because every page or post displayed involves database queries, make sure you’re not overtaxing the expected performance of your hosting option. Plugins that store content in the database give you fl exibility, but also add to the database query burden when you’re generating page output. Again, transients may help you here. ➤ Caching your output may be a viable solution; that is covered more in Chapter 13, “Scalability, Statistics, Security, and Spam.” You will have to weigh the deployment options and come up with a solution to meet your site’s scale requirements and deployment obstacles. c12.indd 315 12/6/12 1:23 AM 316 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCEUsing JavaScript One more tip when using JavaScript in your web design: you may be tempted at times to base your entire site navigation (or another design element) around a super-cool jQuery plugin. The JavaScript may be a really neat effect, but JavaScript should not be the core of your design. jQuery effects should be the sprinkles you put on top of the frosting on the cake. You need to have a solid foundation so that the site still functions and is aesthetically pleasing, even if the JavaScript sprinkles fail. You have to build a site from the bottom up and only add the glitter to a functioning site. Realize that each new JavaScript library and gee-whiz effect you add to your site increases the load time for the end user. Consider if the effect really adds something to your site, or if you are just using it because it looks neat to you. Furthermore, make sure that your site degrades gracefully if the JavaScript does not work. That is, make your cake still taste good even if a slice does not have any sprinkles on it. If your site relies on JavaScript for some functionality to work, and it is the only way for it to work, your site may not be accessible. You have to consider that some visitors will not have JavaScript enabled, or perhaps not even available to them, and your site should be able to elegantly downgrade to support them. In every case, there is a level of effort or visual trade-off required to improve page load times, and you’ll have to measure the work input versus the user experience output improvement.USABILITY AND USABILITY TESTINGYour client is probably not the end user. Furthermore, your clients do not know what their users really want. For that matter, those in the content creation side of things, be they developers or writers, do not know what the eventual users — the readers — really want, unless there is some sort of feedback mechanism, such as testing. Web design is one of those weird trades where everyone thinks they know what is best. Think back to the marketing person who wanted every element to be the most important element on the page, which in the end created a wash of blinking badges. Your clients generally think they know what their users want because it’s what they would want when visiting a site of this nature — that is, the site you are building. This works sometimes. But often, your clients have an intimate knowledge of the topic that their visitor does not have, making it impossible to be objective. If you are serious about having a well-crafted user experience, test early and test often. You have to decide what you are going to test and this really depends on what the goals are for your site. For example, an e-commerce site generally wants to sell products. NOTE This story has been used as the poster child for usability testing for quite a while now, but it is an interesting anecdote about how changing one button made a $300 million difference during checkout: http://www.uie.com/ articles/three_hund_million_button/. c12.indd 316 12/6/12 1:23 AM Usability and Usability Testing ❘ 317How can you apply this type of thinking to testing your own site? A/B testing is a nice way to test what works in a real-world laboratory. With A/B testing, you have two different versions of an actionable web page. Your site will randomly display one version or the other to each visitor. The process involves some nice code trickery and provides an easy way to do usability testing with the general public so it does require that your site be live. Using the results of the test, you can see which version of your action item performs better. This is, in some ways, also how Google does usability testing — it modifi es its services on-the-fl y and sees what generates actual traffi c. If you are going to try A/B testing on your WordPress site, there are several plugins that simplify this process. Some even work in conjunction with Google Analytics’ Content Experiments for tracking. Some other options are to use your family and friends, or call for help on Twitter. This is called crowdsourcing. Any testing is better than no testing. Having a second set of eyes is just a good idea. You do not always have to accept the results and make the changes the users suggest, but you should at least consider them. Again, a fresh set of eyes and a new perspective from someone who is not intimate with the site, as you are, is a good idea. If your budget doesn’t have room for usability testing, use your family and friends and watch them interact with your site. Observing how they fi nd information enables you to isolate places where your design can be improved, and listening to their comments enables you to see what is good and bad about the overall feel. Generally, your family and friends represent the average user’s computer skills and make a nice test audience. Likewise, you can solicit help from strangers via social networks. However, the results you get back vary greatly. Generally, people will be polite and tell you one or two little things either positive or negative, but rarely will you get a cohesive user test back. It is just too time-intensive for the average Joe. You may be able to get more focused results by enlisting your local WordPress User Group. These are likely fellow developers and they will have that sensibility in their feedback. Some groups are more heterogeneous with developers and users, especially on show-and-tell nights. This can be a good opportunity to solicit some feedback and testing. If you do have a budget, many sites are available that provide you access to user testing agents. Generally with these services, you submit your application or site and provide some goals for the user to achieve. You can also select which level of computer literacy you are targeting. The service then contacts its agents, who are average users at home, and using special software, the user records a session while trying to accomplish your goals. We have used one of these services to test a whole new front-end interface to one of our core web applications (not WordPress-related). The resulting videos allowed us to watch how the user inter- acted with the site and provided audio commentary from the users. Some comments were quite overt whereas others required us to interpret the emotions of grunts and “OKs.” In the end, the user testing showed us some places that required immediate improvement to make the actions more clear and reinforced some changes that were made based on more experienced internal focus groups. The WordPress team has done some user testing with the Dashboard in the last several releases. It seems that the administration dashboards were receiving complete overhauls every couple of versions. WordPress is, by virtue of being community-developed, a terrifi c example of crowdsourcing, in both c12.indd 317 12/6/12 1:23 AM 318 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCE development testing and usability. These user tests focused on what features WordPress users used the most and directly led to the development of the QuickPress and other features. This crowdsource testing has led to the very usable control panel. Along these same lines, a little user testing goes a long way in improving the layout and design of your site. It is usually overlooked because developers are smart people and often know best, but you are also very intimate with the site and the fresh perspective can make your site better if you listen to some of the advice.STRUCTURING YOUR INFORMATIONHow your site is organized is critical to your visitors and to search engine spiders. In general, WordPress does a good job of keeping your content organized. After all, that should be a core function of a content management system. However, you do have to put a little thought into the overall structure of your site. One of the fi rst things you want to ask clients who want to redesign their site, or develop a new one, is to create an outline of the pages or content for the new site. This forces the client to think about the structure and organization of the entire site from a 10,000-foot view. Including what type of content each outline item represents also helps in structuring the overall fl ow of the site. Using this outline, developers are able to stub out an <a href="/tags/Information_architecture/" rel="tag">information architecture</a> of post categories, pages, and parent pages that will align with client’s outline and make creating the site a smoother operation. This also allows the client to see the layout of the site with dummy copy, such as lorem ipsum, early in the process to make any structural changes as needed. Once upon a time, there was a golden rule for websites that no page in your site should be more than three mouse clicks deep. This was back in the days when dialup connections were the most prevalent form of Internet access. Although we are not fans of deep sites, we are not sure if this rule is still true today. It’s not that the attention span of the visitor has increased at all; in fact, it has probably diminished. And certainly broadband is more widespread nowadays, but it is not page load times that are affecting our opinion here. The short answer is: Search has largely replaced top-down navigation. In our opinion, people do not go to a website’s index page and run through the global navigation to fi nd the particular topic, article, or product they are looking for. Rather, they go to a search engine. The search engine provides a link to the exact page, or as close as it can get, regardless of how deep in the site it is. So, although we still favor “everything in three clicks” as a design rule, it is only because it adheres to the K.I.S.S. methodology and makes your site easier to use. But do not think this is a hard-and- fast rule, as sites are far more complex and encompass more content than they did when this rule was in favor. Putting in effort to make your content easier to fi nd through search engines, and then structuring the content itself with the “three clicks rule” will together improve the user experience. This is also the ideal time to evaluate what the individual pages or sections are titled. Here is a sad truth of web design: no one actually reads your content. In a 2006 study by Jakob Nielson (http://www.useit.com/alertbox/reading_pattern.html), the researchers found that visitors c12.indd 318 12/6/12 1:23 AM Structuring Your Information ❘ 319 scanned the content of a web page in a very fast F-shaped pattern, meaning their eyes scroll down the left-hand side and skim the headers searching for the content they are looking for. The year 2006 seems like a long time ago, and it is in the technology world, but this study has been continually cited since. Again, this is not a blanket statement. Obviously, people do read the articles and content on websites or there would be no reason to have them. But, when you are still trying to attract visitors and get them to stick around on your site, what should you take away from this study? Headers matter. Headers should be concise and descriptive. Your content should start with the most important and evocative information and then get more in-depth. They should also be properly formatted to use the different levels of HTML headers (more on this later). Headers should contain action words. They should be interesting and make visitors want to read your content, assuming that is your goal. Given that visitors are scanning your site, having actions and descriptions in your headers will allow the visitor to get the overall gist of your page, help them fi nd what they are looking for, and possibly entice them to read the rest of the section. For example, which of the following outline structures is more meaningful and interesting? This one: ➤ How to Use WordPress ➤ Overview ➤ The Technology ➤ Software ➤ Hardware ➤ How to Get StartedOr this one: ➤ Publishing Your Content on the Internet Using WordPress ➤ What Steps Are Involved? ➤ What Do I Need? ➤ Installing the Applications ➤ Confi guring the Server ➤ Getting Started PublishingAs you can see, with the fi rst outline, you grasp the general idea of the website. But the second outline is much more engaging and draws you in with actionable tasks. You can also see the structure of the site and how it fl ows. Remember back in school when you had to write an outline with several levels of headings? This is the same endeavor. Your content should have structure and headings and supporting paragraphs. If a heading intrigues a visitor enough, he will read the supporting paragraphs. If not, he will scan on to the next header. Funny how school actually taught you things you can use in real life, isn’t it? c12.indd 319 12/6/12 1:23 AM 320 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCEGETTING YOUR SITE FOUNDSearch engine optimization (SEO) is how to get your site discovered by the search engines. One of the key ways to do this is to use the permalink structure in WordPress. These search engine–optimized permalinks are one of the key features that actually show up in the results pages of all the search engines. Making them meaningful and descriptive is a must. Unfortunately, out of the box, the WordPress URL structure uses the query string post identifi er format (http://example.com/?p=100). For compatibility reasons, this is the default because it works across the board on different platforms and servers. Given the choice in a search engine results page between these two URLs, http://example.com/?p=42 or, http://example.com/this-is-the-information-you-want which would you choose? The choice is pretty obvious. With the second option, the visitor or potential visitor at least has an idea of what he is going to fi nd at the site. This descriptive URL helps with search engines and click-throughs because the savvy web user knows to look in the status bar of his browser to see the target site. Therefore, we heartily recommend that one of the fi rst things you should do when setting up a WordPress site is change the permalink structure, as shown in Figure 12-3. Of course, you have to be on a platform that will support them.FIGURE 12-3: Setting the permalink structure in the Dashboard c12.indd 320 12/6/12 1:23 AM Getting Your Site Found ❘ 321Shorter URLs are generally better because they are easier to type, yet they need to maintain some inherent descriptive nature. Therefore, we recommend the Post name setting, which is the same as a custom permalink structure using /%postname%/. This will use the slug from your post or page and create the nice SEO-friendly URLs referenced in the preceding example. In previous versions of WordPress using this setting included a heavy duty parsing penalty during the search. That is, the database query really needed a number to get good performance. However, as of WordPress 3.3, the database query rules have been simplifi ed and improved with the result being a performance boost during parsing. Additionally, you have two optional fi elds on this control panel to rewrite the category and tag base URL elements. For example, when you visit a category page in your WordPress site, the URL usually looks something like http://example.com/category/cool-stuff/. You can replace the word “category” with whatever you key into these optional fi elds. You can just use a letter c for category and t for tag to make the URLs shorter, but some creative uses of these fi elds can lead to some interesting and meaningful URL structures.NOTE Chris Shifl ett has an interesting post on his PHP Security blog (http:// shiflett.org/blog/2008/mar/urls-can-be-beautiful) that discusses how URLs can be beautiful. At the time, Chris worked for OmniTI, and the URLs for the new site involved action words that conveyed a very clear meaning: for example, http://omniti.com/is/hiring and http://omniti.com/helps/ national-geographic.Duplicate Content When a search engine is spidering your site, if you have duplicate content, or more specifi cally, multiple paths to the same content, the search engine may divide up your ranking (and SEO equity) across these multiple pages, diluting your overall ranking for any specifi c content piece. This section addresses how to keep multiple paths to content from appearing as distinct content views. WordPress practically encourages duplicate content. Your posts are shown on the index page and on the category page for each category the post is in. Each tag creates a tag page for that content; plus your posts are kept in the yearly and monthly archives. So, while this provides you multiple paths to get to your content, which was considered a good thing in a previous section, it also weighs you down with you with duplicate content issues. Duplicate content on your own site may or may not actually be a bad thing; the jury still seems to be out on it. For example, the Google crawler, which indexes your site, has built-in logic to try and determine the nature and cause of your duplicate content. The crawler knows how to handle different views of the same content, such as for print versions. It also does its best to reinforce the primary source of the content — for example in a WordPress site, the single.php view. In addition, Google provides a Webmaster Tools site that can provide insight into how the Google crawler sees your website. Use the Google XML Sitemaps plugin from Arne Brachhold, available online at http://wordpress.org/extend/plugins/google-sitemap-generator/. This creates c12.indd 321 12/6/12 1:23 AM 322 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCE an XML sitemap for Google to use when indexing your site, which helps the spiders fi nd everything. But Webmaster Tools also has some other interesting tools and investigative features. For example, under Optimization ➪ HTML Improvements, you can see duplicate content that the spider saw, as shown in Figure 12-4.FIGURE 12-4: Google Webmaster ToolsFurther clicking into the duplicate content suggestion will indicate exactly which pages are causing you problems. In all fairness, Microsoft’s Bing.com has a similar set of tools that are just as nice.Additionally, you should edit your robots.txt fi le. The robots.txt fi le provides some more guidance to the search engine spiders on what should not be indexed. By default, a spider will aggres- sively index whatever it can fi nd. The robots.txt fi le tells the spider what it is explicitly not allowed to index. Again, you are relying on the spider to play by the rules, but here is a good start for your robots.txt fi le:Sitemap: http://www.example.com/sitemap.xmlUser-agent: * Disallow: /cgi-bin/ Disallow: /wp-admin/ Disallow: /wp-includes/ Disallow: /wp-content/plugins/ Disallow: /wp-content/cache/ Disallow: /wp-content/themes/ Disallow: /trackback/ Disallow: /feed/ c12.indd 322 12/6/12 1:23 AM Getting Your Site Found ❘ 323Disallow: /comments/ Disallow: /category/*/* Disallow: */trackback/ Disallow: */feed/ Disallow: */comments/ Disallow: /*? Allow: /wp-content/uploads/If you include your sitemap, don’t forget to change the URL in your robots.txt fi le to match your actual site.Trackbacks and Pings Google increases your page rank by counting links to your site through trackbacks. Trackbacks are a validation of your content by other sites. They started as a way for one site to inform its readers that they may be interested in this content from another site and also to let the other site know “Hey, I talked about your content and here’s the link.” They can basically be thought of as comments about your content on a remote site. By default, WordPress groups comments and trackbacks together, further validating that they are remote comments, but this can often look messy to your reader. A common practice is to separate out the trackbacks from the actual comments in the comment loop. The Twenty Eleven theme does this for you in the default templates using the twenty_eleven() function found in functions.php: switch ( $comment->comment_type ) : case 'pingback' : case 'trackback' : ?> <li class="post pingback"> <?php _e( 'Pingback:', 'twentyeleven' ); ?> <?php comment_author_link(); ?> <?php edit_comment_link( __( 'Edit', 'twentyeleven' ), '', '' ); ?> <?php break; default : ?> <li <?php comment_class(); ?> id="li-comment-<?php comment_ID(); ?>"> <article id="comment-<?php comment_ID(); ?>" class="comment"> As the comments are walked, this function determines if it is a trackback or an actual comment and displays it accordingly. You can review the Twenty Eleven functions.php template fi le for more information and to view the remainder of the function. You can also override this function in a child theme to make the display logic your own. What this gets you is a clear separation between the active discussion on your site, for your visitors to participate in, and a list of related sites that have also mentioned your content. They can be divided logically and visually, making it easier to digest for the visitor. Pings, on the other hand, notify other sites when new information is published. Generally your WordPress site would ping an update service, such as Ping-o-Matic, that you have new content on your site. Likewise, if you are writing about content on another WordPress site, your site may ping that other site to let it know about your content. In this respect, pings are similar to trackbacks. c12.indd 323 12/6/12 1:23 AM 324 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCEPinging update services is a good way to drive traffi c to your site. Some sites take the information from these update services and create information link sites about them. The theory is that casual surfers of these sites may discover your content related to a topic they are browsing. In this respect, pinging works very much like a push version of RSS or tweeting your new content. Signing up to use an update service such as Ping-o-Matic is really simple to do. Simply browse to the site at http://pingomatic.com/, sign up your site, and it starts working. There is not much to it.Tags and Content Sharing Sites Technorati.com was one of the fi rst sites to utilize these update services and create an aggregation of blogs. Technorati tags enable you to put your content into categories at www.Technorati.com. Basically, you insert a tag on your page that points back to Technorati so that your content is aggregated by tag along with similar posts. Technorati tag functionality is waning, however, in lieu of new notifi cation processes. While the Technorati site is not the important add-on to WordPress that it once was, it is still an easy place to get your content listed with relatively little effort. You now have plenty of ways to advertise new content with the advent of social media sites such as Facebook, Reddit, and Twitter. For example, Chapter 11 covered how to add social networking buttons to your posts, which serves as a simple way for you to effectively crowdsource the notifi cation processes through these new aggregators. Having your readers recommend content and pass it on to tag-oriented sites improves the chances of your content being found through channels other than search engines. In practice, the pinging functionality is not used very much. Rather, a custom application is used that parses the RSS feeds of the various sites and tweets new posts as they are posted. In certain situations, this notifi cation works better.HOW WEB STANDARDS GET YOUR DATA DISCOVEREDHTML is text markup. That is literally what it means. When HTML was fi rst developed, the intention was to take content and mark it up in a consistent and meaningful way. Many different HTML tags accomplish this. It was for scientifi c and academic use and the majority of content fi t this nature. Eventually, the marketers showed up and got their greasy hands involved. They wanted fancy layouts, graphics, sales pitches, and pretty pink ponies. To accomplish this, designers and developers, both good and bad, lost sight of the original markup and used whatever means necessary to create the best-looking site on the web. This included table-based layouts. In recent years there has been a back-to-basics mentality among the better developers. This likely includes you, because you are reading this book. These developers recognize the power of separating concerns, such as presentation and content, CSS and HTML. They also recognize the advantages of using semantic HTML.Semantic HTML POSH stands for plain old semantic HTML. This acronym expresses a back-to-basics mentality in the underlying HTML of websites. For all the glittery design and fl air, developers can use CSS to make it happen. Look at CSS Zen Garden for an example. c12.indd 324 12/6/12 1:23 AM How Web Standards Get Your Data Discovered ❘ 325Why should your site use POSH? There are a few reasons. First, it is the best thing for the future web. Paying it forward, if your site continues to use semantic HTML, browser manufacturers will continue to support it in their browsers. Second, for the developer, it makes the content easier to validate and maintain. There is much less cruft in a properly semantic HTML document than in one that is coded old style. Consider this,<div style=" background: #F0CCFA; border: 1px solid # D894EB; color: #f00; font-size: 2em; margin: .25em 0; padding: .5em;"> This is my subheading </div> versus this:<h2>This is my subheading</h2>And that is not even really old style. This still uses CSS instead of the multiple nested tags that really clutter up the old HTML documents. Valid, lean HTML is easier to maintain. It is that simple. Speaking of lean, stripping all the cruft out of your HTML can really make your pages load faster. Think of all of the extra markup that is moved out of each page load and into a browser-cached CSS fi le. This can be a signifi cant weight loss for your pages. The third reason is accessibility. Structuring your HTML semantically increases the likelihood of screen readers fi guring out your content and having it make sense to the visitor. Finally, valid semantic HTML helps with search engine optimization. Search spiders are not very smart. They do not care how pretty the site looks or the cool new graphic treatment you created. They only care about the content. And they cannot think for themselves. Semantic HTML conveys the meaning of the text you are marking up. That is why it is called semantic, after all. Using the proper HTML tag for the content is the fi rst step. For example, six levels of headers are available to you in HTML. Using them in the correct order is essential for SEO. Similar to using a site outline to map out your site, this is also how the crawler knows the order of your content. Even if you separate your CSS properly into a style sheet, the spider cannot determine the value of this HTML:<div class="pagetitle">My Site Is About Something Important</div>If you use the <h1> tag, however, the spider knows that this is the header for the entire page and attributes this content with the appropriate weight.<h1 class="pagetitle">My Site Is About Something Important</h1> c12.indd 325 12/6/12 1:23 AM 326 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCEScrolling down your content, you should use the appropriate levels of headers for additional content. The general consensus is that each page on your site should have only one <h1> tag to indicate the top level of each rendered page. Conventional wisdom is that this <h1> is reserved for the name of the site and then there can be multiple instances of the other heading levels as needed. The only fl aw in this is that the name of your site does not really change, so it is not the <h1> that matters the most for each page. Using headers in this manner makes the <h1> really irrelevant; the <h2> would be the page title describing the rendered page’s content. It’s easy to understand both sides of the argument; you will have to make your own decision.Images should always have alt attributes. This informs the spider what the image is rendering because the spider cannot see the graphic itself. This information is also what screen readers use.The <div> tag is for blocks of content and the is for paragraphs. Use the more meaningful and to emphasize and strongly emphasize your content. Also discussed later in this chapter are HTML5 tags for specifi c blocks of content, such as <header>, <footer>, and <article>.Use proper lists to organize your data. Ordered lists (<ol>) and unordered lists (<ul>) are easy ways to convey information to the spider. A properly formatted list is semantically more information to rate than a paragraph fi lled with tags. There is also the lesser-known defi nition list (<dl>) element, which is very effective in paired information lists, such as Frequently Asked Questions. This list and explanation of HTML attributes can go on and on. In short, semantic HTML is all about using the proper HTML tag for its intended use. It is worth reading through the W3C specifi cations and learning the different tags and their purpose. Adding these additional tools to your bag of tricks will make you a better developer, but will also make your pages lighter, more meaningful, and more accessible, all of which are good things for your visitors and your search engine rankings.Valid HTML For, you, the developer, valid HTML and valid CSS is just plain easier to maintain. It is a simple fact. If your code is structured correctly, you can get in and out and make the changes you want quicker. We still have some ancient table-based layouts lying around from clients that have never wanted to update the look of their site. If you have not had to work on one of these in a while, it’s astonishing to remember how hard they were to work on. But at the time, this is what we had. Valid HTML also helps in solving cross-browser rendering issues. All developers dread the day they have to test their great looking site in one of the older less standards-compliant browsers. You know which one. It is important that the developer has completely consumed the requisite amount of coffee and moved all sharp objects out of arm’s reach before opening this browser for testing. Inevitably, something will not be right. Having validated HTML is the fi rst line of attack when dealing with this browser’s rendering challenges. Always start from a clean code before taking measures to make it look reasonable in these browsers. And have hope, maybe, that someday this browser will not be around anymore. Fortunately, supporting the older browsers is becoming easier as users become more aware of the need to upgrade and try alternate browsers. In addition, some new tricks in the theme HTML allow you to target specifi c browsers with conditional comments. For SEO, it is back to a “spiders are not very smart” problem. Valid HTML makes your content easier for the spider to understand and therefore rank. If your HTML is not properly valid, the search c12.indd 326 12/6/12 1:23 AM How Web Standards Get Your Data Discovered ❘ 327 engine can lose the content that is not visible to it while it is looking for the closing tag or attribute. This can severely limit the content that is viewable to the spider and hinder your site’s ability to rank. Browsers tend to be more forgiving on invalid HTML and do their best to render what they can, but a spider is working on speed and quantity of content to digest. The spider is just going to breeze past anything it does not understand. Again, use a means like Google Webmaster Tools to see how a browser perceives your site. Many resources are available to validate your HTML, including the W3C’s own Markup Validation Service at http://validator.w3.org/. In addition, most browser developer tools have a plugin or extension to use the W3C’s validator service.Microformats Microformats are the more complicated brother of POSH. The idea is to add simple tags to HTML that convey contextual information for the HTML content. Once you see how they work, some are an almost natural way of dealing with the content, similar to an implementation of XML in HTML. The microformat convention is to format certain information in HTML so that it is reliable and can be discovered by microformat-enabled tools. For example, you will often see contact information and addresses expressed in a microformat syntax. You might even be using microformats already and not even know it.For example, the Technorati tags mentioned earlier are microformats. The rel attribute on an anchor tag linking to Technorati.com indicates that the page you are linking from has been tagged for Technorati consumption. This is a microformat:<a href="http://technorati.com/tag/wordpress" rel="tag">WordPress</a>Another common microformat that is built into WordPress is the XFN (XTHML Friends Network). This microformat is simply an attribute you place on links to indicate your relationship with that person. This feature is built-in on the Links control panel, also known as your blogroll. Using this handy control panel, you can easily add microformat attributes to your link indicating how and where you know the individual you are linking to. For example, consider the settings shown in Figure 12-5.FIGURE 12-5: Editing the XFN of a link c12.indd 327 12/6/12 1:23 AM 328 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCEThese settings will render the HTML as:<a title="WordPress.org" rel="friend colleague muse" href="http://WordPress.org">WordPress.org</a>This is a simple yet effective way to create some meaningful information about the link. The key is the simplicity of it. To a web browser, this information does not affect the rendering. In fact, only recently has Internet Explorer even allowed developers to use the rel attribute as a CSS selector. But imagine the power when a search engine spider or other tool can create a social graph out of the information contained in microformats. You can fi nd more information about the XFN at http://gmpg.org/xfn/. Another microformat that is gaining traction is the hCard. The hCard microformat is for displaying contact information for a person or organization. It is the HTML rendering of the common vCard format used in e-mail and e-mail address books such as Microsoft Outlook and Mac OS X Address Book. Here is a sample hCard:<div id="hcard-David-Damstra" class="vcard"> <a class="url fn" href="http://mirmillo.com">David Damstra</a> <div class="org">Professional WordPress</div> <div class="adr"> <div class="street-address">123 Main Street</div> Grand Rapids, MI, 49525 </div> </div> Obviously, the information has been changed so you cannot stalk David. The hCard is one of the most common microformats used. It is very similar to the vCard format used in e-mail and address book software. Render the preceding hCard on your site and it looks like an innocuous address block. But running this same code through a tool or spider that understands this microformat can lead to much more intelligent use of the information. Microformats allow external tools to make better use of your blog posts, ideally driving more viewers to your site. Conversely, they make use of external services using metadata in your microformat tagged posts. One example is the GeoMark plugin that converts location information in a post into GEO microformat tags stored as post metadata that is also passed on in RSS feeds of your post. Currently, search engine spiders do not weigh microformatted data any differently than the other content on your site. However, microformats are emerging and continue to gain traction, and eventually spiders will recognize them and be able to harvest the semantic data included. The bottom line is that microformats are becoming the de facto convention for marking up this type of information. So although the microformat is spidered the same as traditional content, by using the microformat conventions you are working toward future-proofi ng your content. c12.indd 328 12/6/12 1:23 AM How Web Standards Get Your Data Discovered ❘ 329Microformats are an investment in the future. They are relatively simple ways to structure specifi c content so that at a later time this information can be used to do something informative or cool. Hopefully in the future, you’ll be able to search for a name and fi nd that person’s social graph along with it, search for a business and automatically have the contact information logged to your smartphone, or search for a location and time and have an aggregated list of events that are occurring in the vicinity. The data is starting to emerge, so the tools cannot be far behind.HTML5 While talking about progressive HTML elements, let’s take a quick detour into HTML5. While not WordPress-specifi c information, this topic it is very appropriate for web development in general. What is HTML5? Basically, it is the next iteration of the HTML standard that web developers have been using for years. But the term itself is a little loaded. It has become a marketing term to encompass many, many aspects of web development above and beyond the basic HTML syntax. It’s essentially a buzz term for executives to indicate the latest and greatest web development techniques, sort of like Web 2.0 was in the late 2000s. So when you hear someone mention HTML5, you have to ask yourself whether they mean HTML5 specifi cally, or the current crop of web development techniques, including HTML5, CSS3, and Javascript. Let’s focus on actual HTML5. What is included in HTML5? Quite a bit actually — some things that you can use immediately, some that you can use selectively depending on your audience, and many things that you will have to wait for browser adoption to really take up. The biggest feature of HTML5, and likely the one most web developers think of fi rst, is the new tags. HTML5 introduced many HTML elements that are more descriptive and have a semantic purpose. With a little help, you can actually use these new tags today, but more on that in a minute. If you have been developing websites or WordPress themes for a while, you will recognize the common <div id="header"> and <div id="footer"> as pretty pervasive to all websites. With HTML5, these elements are replaced with the new <header> and <footer> tags. Additional tags have been created that are particularly appropriate to WordPress themes, including <nav>, <article>, and <aside>.As you can imagine, the <article> tag specifi cally fi ts right into the pages and posts paradigm of WordPress. In fact, the Twenty Eleven theme actually uses these tags for that purpose. The Twenty Eleven theme leverages many of the new HTML5 tags in the theme templates and is a good place to start when exploring how to use these tags in your own custom themes. Another good resource for seeing the HTML5 tags in action is the HTML5 Boilerplate by Paul Irish , online at http://html5boilerplate.com/. This resource is not WordPress-specifi c but takes all the best practices and recommendations and bundles them together in a HTML5 starter set. Additionally, there are several WordPress themes that have been created using the HTML5 Boilerplate as a source. A quick cautionary note about HTML5 tag elements: they are not directly supported by all browsers, notably Microsoft browsers prior to Internet Explorer 9. However, all is not lost. There are JavaScript solutions to make these older browsers recognize the new HTML5 tags and let you style them appropriately. The Twenty Eleven theme uses HTML5Shiv (http://code.google.com/p/ html5shiv/) to achieve this functionality. Another option, the one used by HTML5 Boilerplate, is the modernizr.js from http://modernizr.com. Modernizr includes the HTML5Shiv to allow c12.indd 329 12/6/12 1:23 AM 330 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCE older browsers to recognize the new HTML tags, but also includes additional feature detection to enable you to use additional HTML5 features and CSS3 attributes. Which one you use is dependent on your needs. In our opinion, HTML5, with the appropriate JavaScript, is safe to use in production sites. You can and should be building new themes with the HTML5 tags. The fact that Twenty Eleven uses these tags is an additional stamp of approval from Automattic. Just make an evaluation of the browser you need to support and make a decision based on your requirements. In addition to the new more descriptive HTML tags, HTML5 has a bevy of additional features. As mentioned before, some of them you can use today and some of them you’ll need to wait until browser adoption takes off. A convenient website for determining browser support is http://caniuse.com. This website tracks past, current, and development versions of the common web browsers and assesses their support of new features, including HTML5, CSS3, and others. It does not take into account when you apply a JavaScript shim such as HTML5Shiv or Modernizr.js. The site tracks out- of-the-box support. This can be a very convenient resource when you are planning your design and settling on which browser to support and which features you want to include. Some of the additional features of HTML5 include offl ine storage, which could be used for mobile device web applications when the mobile device does not have an Internet connection. Media and canvas tags are available for delivering certain media fi les directly in the browser. An especially exciting feature is the new form validation and helpers. These updated form tags include the actual validation mechanism built right into the browser and include additional features such as place- holder text on the forms and formatting. Basically, the new form features are trying to solve the problems on the web that you currently deal with everyday.As mentioned, HTML5 has many more features; to learn more, check out http://www.html5rocks.com.CSS3 This section is about cascading style sheets, version 3, or CSS3. This is the next iteration of styling websites. Currently, many of the new CSS3 styles are implemented in browsers using browser-specifi c prefi xes. This allows you to try out these new features on specifi c browsers, but also makes maintenance more diffi cult when you have three to four lines in your CSS fi le to produce the same effect on different browsers.Again, http://caniuse.com is an invaluable resource for determining which features you can use across browsers using offi cial CSS3 syntax and when you need to implement browser-specifi c prefi xes. Also, the general consensus now is that developers do not need all browser versions to render websites exactly the same. Being reasonably close is usually good enough. Also, adding fl ourishes and design details to browsers that support them while leaving older browsers to render it without them is also acceptable. This is generally called progressive enhancement. A common example of progressive enhancement is rounded corners. Imagine your design mockup has rounded corners on certain design elements. Prior to CSS3, web developers had several tricks for making rounded corners, including images, both positive and reverse in color, as well as countless JavaScript libraries. With CSS3, rounded corners is a simple CSS3 style using the border-radius style. c12.indd 330 12/6/12 1:23 AM Searching Your Own Site ❘ 331You can apply this style and check it in your browser, and it works fi ne. However, if you look up border radius on www.caniuse.com, you will notice that Internet Explorer 7 and 8 do not support this style — which is why you had all those tricks in the fi rst place. At this point, you can choose to accept progressive enhancement. The website still renders fi ne in Internet Explorer, but certain elements have squared off corners. Browsers that support the enhanced effect have the look you intend. The thought here is that eventually (one hopes), all browsers will converge on the standards, and eventually (one hopes), your enhanced design will become the design that everyone sees. The fl ip side is that you still have to test your design in the older browsers to make sure they do, in fact, render reasonably well, assuming you do need to support these older browsers. One of the biggest, most immediately accessible features of CSS3 is a media query. Media queries enable the designer to tailor a website to specifi c screen resolutions, prompting a new type of mobile website experience. This topic is covered in a little more depth later in this chapter. HTML5 adds new semantic tags to make your site’s content more understandable to devices that are rendering or crawling your data. Couple this with CSS3 styling to add new appearance and design attributes to the look and feel of your content. Together they are making the user experience easier to maintain for both human and nonhuman consumers.SEARCHING YOUR OWN SITESo far, you have learned how to make your site visible and effective in the big search engines by structuring, organizing, and coding your site to raise your listings, or at least get the ranking you deserve. What happens when the visitor gets to your site and uses the built-in on-site search? Do the same rules and guidelines apply? The answer is yes and no. The SEO principles and practices discussed are a solid foundation to build on. They are tried-and-true rules, although the search engines can make up their own rules and change them on a whim — you are in the Wild West Internet. The change lies in the built-in WordPress search.Weaknesses of the Default Search Out of the box, the WordPress search is probably good enough for most small sites. After all, this was how WordPress evolved, and good enough was good enough. But as your site grows, or as you build larger, more prominent sites, good enough is no longer good enough. The default WordPress search has some serious defi ciencies for larger sites, and there are a couple of important challenges to be addressed here. Results are sorted by date, not relevance to the search terms. WordPress loves showing content in chronological order. Chronological posts are the heart of the WordPress engine. So the default search will return results of the search term in reverse chronological order. It suffers from a recency effect. Even if you have a large, excellently written article about a topic, if newer posts about the same topic exist, the newer ones will get top billing in the results pages. Relevance to the search terms does not matter. There is no weighting in the results for search term counts. The search strictly glances through all the post and page content, and if the term appears, it fl ags it for the results and then spits them out in date order. c12.indd 331 12/6/12 1:23 AM 332 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCEThis brings you to the next shortcoming. The search only searches some of your site’s content. The default search only looks in the post content and page content — not the headlines, not the comments, not the links, not the categories, not the tags, nothing else. You learned earlier that headlines matter, and visitors only read the headlines, so if your catchy article headline sticks in someone’s head and they return to your site to search on some variation of your headline, search may not fi nd it because headlines are not indexed. Ideally your content supports the catchy headline you made, so eventually your content will be found with search. But there is so much more content to your site that could be used to empower the search to make it more effective or even to broaden the search. After all, it could have been one of your comments that really sparked the interest. Next, there is no logic to the search. That is, you cannot use any sort of Boolean syntax in the query. The search is a straight up “fi nd this word in the posts” kind of search. Search power users use Boolean syntax all the time to create very refi ned search engine results. WordPress search does some silly things with these keywords. For example, try searching on your WordPress site using Boolean keywords in your search string, such as searching for keyword1 AND keyword2. In this case, you want to fi nd content that contains both keywords. You will fi nd that WordPress search treats the AND just like any other keywords and will include content that contains all three words, that is, the keywords and the word AND. In all likelihood, you will have no results. WordPress search handles a Boolean “or” in the same fashion. Try searching for content with either keyword1 or keyword2 in it using the search string keyword1 OR keyword2. Again, WordPress search treats the OR just like the actual keywords. Now search for either keyword independently and compare the results. Depending on your site, you will notice that the OR search does not contain the same results as the two independent searches combined. After some simple experimentation, you will see that WordPress search does not know how to handle these generic Boolean queries. Some people complain that the WordPress search does not highlight the search terms in the results. In some situations highlighting is handy; other times, it does not affect the usefulness of the search results. This defi nitely seems like a personal developer choice, which makes it ripe for a plugin. On the other hand, this could easily be handled with some creative PHP and CSS also. The WordPress search has been good enough, but it does not take advantage of some available tools such as MySQL FullText search or other third-party search engines such as Lucene or Sphinx. Understandably, WordPress needs to keep the installation process simple and reduce the dependencies on external software packages. This defi nitely complicates the whole installation. But, if a developer is capable and willing to integrate these other packages, why not let them? Some of these seem like big deals, and for some developers they certainly are. But search is a pretty personal thing. Different developers want it to have specifi c functionality or algorithms and because WordPress has a great plugin system, each developer can have what he wants. You can either fi nd an existing plugin or you can write your own to scratch that pesky search engine itch.Alternatives and Plugins to Help Obviously, we are not the fi rst to recognize these inadequacies in the default search mechanism. Some very talented developers have set out to create plugins that enhance or replace the built-in search. c12.indd 332 12/6/12 1:23 AM Searching Your Own Site ❘ 333Many, many plugins are available. Some target specifi c issues, and others change the whole search process. Following are some of the more popular search engine plugins for WordPress.Search Everything (http://wordpress.org/extend/plugins/search-everything/) by Dan Cameron of Sprout Venture extends the breadth of the WordPress search to include the different content sources in the index, including comments, tags, and categories. Search Everything also has settings for search term highlighting, and all the settings are managed from an Administration control panel.Relevanssi (http://wordpress.org/extend/plugins/relevanssi/) by Mikko Saari is another search replacement plugin. This plugin comes in both a free version and a premium version that includes support and additional features. This plugin includes search term highlighting and also searches additional fi elds such as comments, tags, and custom fi elds. But the biggest advantage of this plugin is that it uses syntax that will be familiar to Google users. This plugin supports the Boolean logic operators AND and OR. It supports phrase searches when included in quotes and partial word matches. This is much more of the search experience users are expecting. Alternatively, you can actually match the experiences users expect by using a Google Custom Search Engine (http://www.google.com/cse/). Google Custom Search Engine (CSE) is a service offered by Google to provide your own subset of Google’s existing search results. Google offers two programs for your Custom Search Engine. The basic free edition enables you to customize the look and the index but includes Google Ads. The second tier starts at $100 per year to remove the ads and the Google branding, if you desire. Either option integrates into your WordPress site in the same way. There are several plugins for integrating a Google CSE into your site. Alternatively, you can integrate it manually using page templates and the code provided by Google. Page templates were covered in depth in Chapter 9, but here is a quick example of how you could set this up. First, sign into the Google Custom Search Engine control panel and create your new custom search engine. After you have set it up, you will want to modify the look and feel. Change the layout to the Two Page option. This enables you to put the search box anywhere on your website and then have a specifi c page designated for the results. Save this setting and get the code. Here you need to do a little juggling to create the page you need for the code page of the Google Custom Search Engine. Switching back to your WordPress site you need a specifi c page for your search engine results and you want to assign that page a specifi c template. First, make a new page template for the results. It could be as simple as the following:<?php /* * Template Name: Google Search Results */ get_header(); ?> <div id="primary"> <div id="content" role="main">  </div> </div> <?php get_footer(); ?> c12.indd 333 12/6/12 1:23 AM 334 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCENotice there is a spot in the content area where you will paste in the search results code provided by Google. Save this template fi le and push to your WordPress theme on the server. Next, you need to make a page that uses your theme to show the results. Create a new page on your WordPress site. Select the page template you just pushed and publish the page. Because you are using the preceding page template, you do not need anything in the content area of the page; Google will fi ll it in for you. Finally, you need to create the search box on your WordPress installation. Probably the simplest method is to use a text widget in one of your widget areas. Simply copy the Search box code provided by Google and save it in a widget. Now you need to test that it all works together. Depending on when your website went live, you may need to wait for Google to index your pages. To really leverage the power of a Google Custom Search Engine, make sure you connect it to your Google Analytics and Google Webmaster Tools accounts. In addition, evaluate some of the additional features in the Google Custom Search Engine such as Refi nements to modify the indexing, and Promotions to highlight certain search results.MOBILE ACCESS AND RESPONSIVE WEB DESIGNMobile access continues to be a hot topic because of an enormous market uptake of smartphones with high-speed data services and stores that proliferate fat client applications for these phones. Forrester , a global research fi rm, reports that more than half of the world’s population has a mobile device (http://blogs.forrester.com/susan_huynh/12-02-21-mobile_internet_ users_will_soon_surpass_pc_internet_users_globally). Google reports more of its Google+ users are on mobile devices than desktop devices (http://www.engadget.com/2012/06/27/ google-has-250-million-users-more-mobile-than-desktop/). Morgan Stanley has been saying for years that mobile access will exceed desktop access in the next several years (http:// mashable.com/2010/04/13/mobile-web-stats/). Mobile users are clearly an audience you cannot afford to ignore. The question is how much attention do you need to give to this burgeoning crowd. Do you customize an experience for each type of device? Can you keep up with device proliferation? Screen sizes and features and the feature API all vary. There are currently a couple of schools of thought on how to handle this. Leave It Alone The fi rst paradigm, and obviously simplest, is to leave it alone. That is, show mobile browsers your full website. Give them the whole experience that you are providing to desktop users. The idea here is that the newer browsers on the smartphones, such as the Apple iPhone and Google Android devices, can render traditional websites acceptably fi ne. The tech savvy users of these devices know that the browser is limited and the screen is small and they do not expect a stellar user experience. In short, leave it to the user and the device. Tablets and smartphones can zoom and scroll and users are used to these techniques. If you have young children with tablet experience, you c12.indd 334 12/6/12 1:23 AM Mobile Access and Responsive Web Design ❘ 335 probably have fi ngerprints on your desktop monitor from the child trying to scroll the screen and subsequently complain when it does not work. In practice, this method generally works well. All of the information on the website is still accessible on a mobile device. The visitor continues to use learned website conventions and behaviors from the traditional browsing experience. The challenge is the small text and limited screen real estate. Lightweight Mobile Another school of thought is that you have the technology available to create custom themes for these devices, especially with the power of WordPress. Mobile themes hearken back to the lightweight themes of dial-up days to conserve the limited bandwidth available. This makes mobile themes faster to load over the wireless bandwidth. In addition, they should be tailored to fi t the small screen real estate and focus on the information that the mobile visitor is really looking for — often locations and contact information. WPTouch is a plugin that converts your site to look like a native iPhone application. The WPTouch Plugin was created by Dale Mugford and Duane Storey from Brave New Code and is available at http://wordpress.org/extend/plugins/wptouch/. After installing this plugin, your site will automatically detect mobile browsers and offer them your entire site, but in a specifi c mobile-enhanced theme. This theme uses AJAX requests and other effects, giving the illusion of a native application. In addition, WPTouch offers an extensive control panel to manage all the settings. WPTouch also offers the ability to set a custom index page for mobile browsers. This is a fantastic feature and enables the developer to create a custom page for the quick information that the mobile visitor really needs. In addition to the iPhone-inspired theme, WPTouch includes the capability to tweak the CSS to create a theme that matches your traditional site theme. WPTouch also offers the capability for the mobile visitor to select to view the traditional desktop theme. A couple of notes of caution: If you are using a caching plugin, discussed in the next chapter, you will have to set it to exclude showing cached content to the mobile browser. Otherwise, the caching will supersede the WPTouch browser detection and the traditional theme will be shown. Second, every mobile detection behaves a little differently. Should the iPad browser be considered mobile, or is the screen large enough to offer the desktop version? What about the Amazon Kindle with a slightly smaller screen? Should it behave differently if the device is on WiFi or a slower cell signal? Compound these automatic software decisions with user preferences.Responsive Design A responsive design is the current craze. Responsive web design was fi rst proposed by Ethan Marcotte on A List Apart in 2010 (http://www.alistapart.com/articles/responsive- web-design). In essence, responsive web design uses the CSS3 media queries’ functionality, mentioned previously, to reformulate the layout and design of your website theme to match the screen size of the device it is being viewed on. The theory here is that you manage the content and theme at once, and then tweak it for different screen resolutions. That is one set of content for c12.indd 335 12/6/12 1:23 AM 336 ❘ CHAPTER 12 CRAFTING A USER EXPERIENCE every screen size that adapts, or responds the viewing environment through selective CSS rules. In practice, it is much more complex. This works because of media queries. Media queries existed prior to CSS3. Print style sheets are a form of media query that web developers have used for a long time. What changed with CSS3 is that the media queries now support screen resolution calculations. These queries now allow you to apply certain CSS styles only if the screen resolution falls in a certain range, as determined by you. The specifi c intricacies of responsive web design is not WordPress-specifi c and is outside the scope of this book, but let’s take a quick look at how it might work. A common responsive design change on a WordPress site is dealing with the sidebar. On a desktop browser, you have the screen real estate and generally the sidebar is located on the left or right-hand side. This is a traditional website. However, on a mobile screen, where space is much more limited, this sidebar information may not be as important. For example, when viewed on a handheld device, perhaps the sidebar content gets moved below the primary information. Using a media query block in your style sheet, you can change the fl ow of your content blocks. This would leave your primary content, generally considered the most important information front and center on the small screen, and relegate the secondary content to a less prominent position. Again, the actual implementations of responsive website design is a book all its own. Many tutorials and how-tos are available online for best practices and recommendations. Furthermore, many responsive WordPress themes are already out there, including Twenty Eleven, for you to try and explore how they work. Responsive web design is a popular solution among developers to address the mobile audience, right now. It’s a solution deployed on many websites. But the more involved the responsive themes get, the more complicated the process becomes. Anyone remember the days when you made separate website themes for Netscape Navigator and Internet Explorer? Some days, responsive themes feel the same way when you’re managing multiple versions of your site for different sizes, under the guise that you aren’t. You end up troubleshooting and debugging the theme multiple times at the different resolutions. And as devices proliferate, this may become more and more convoluted as you try to match designs to resolutions. The fl ip side is that you are in complete control and responsive web design will only be as complex as you make it. Mobile themes continue to be an up-and-coming area of web development. As smartphones with reasonably supportable browsers become more commonplace, this type of functionality will become a requirement for all sites. You will continue to see mobile optimized themes and responsive themes pop up all over the place. More and more theme frameworks and starter themes are including responsive elements from the start, making the whole process easier. SUMMARYNow that you’ve looked at the user experience that makes your site interesting and available to readers and devices. Techniques included HTML5 and CSS3 as well as general user experience principles. In the next chapter you’ll learn about scaling and securing your site as your audience grows, specifi cally in terms of performance, scaling and security. c12.indd 336 12/6/12 1:23 AM 13 Statistics, Scalability, Security, and SpamWHAT’S IN THIS CHAPTER?➤ Adding traffi c counters to your website ➤ Caching your content for higher traffi c loads ➤ Keeping your WordPress site healthy and secure ➤ Delegating permissions to your usersThe past few chapters have covered how to present your fabulous content in effective and beautiful ways, how to increase the likelihood of visitors fi nding your content, and how to amass various content sources into your WordPress website. What happens when (if?) this all succeeds and scores of visitors fl ock to your site? Well, now you have a live and active site, which opens up a whole range of other challenges you have to think about. In this chapter, you will look at mechanisms to defi ne and measure success, and then deal with the resultant attention you’ll get in terms of unwanted content, malicious visitors, and the need to scale in response to increasing readership.STATISTICS COUNTERSViewing traffi c statistics allows you to see which content on your site is actually bringing visitors in. This shows you what content is working and what is not. In addition, traffi c statistics can show you valuable information about your visitors and their hardware and software setups. This information enables you to tailor your site to accentuate the positive and support your visitors’ browsers to create a more pleasant and meaningful experience. c13.indd 337 12/6/12 1:24 AM 338 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAMStatistics packages employ a couple of different methods for gathering data, and each has its own advantages and disadvantages. Likewise, each vendor puts its own spin on the traffi c statistics. You can gather traffi c statistics in a couple of ways. The grandfather in this realm is to parse your log fi les. Your web server, if confi gured properly, will create log fi les for each and every request and error that it handles. Certain statistics packages can parse these logs and create human-consumable information. Some packages even let you download these logs to your local machine and let it do the busy work offl ine. The second method is to put a snippet, usually JavaScript, on each page of your site that reports back to a central server, which then accumulates the data and makes it meaningful to you. This method is the current trend. Each of these packages has an available WordPress plugin. Each package also varies in its specifi c vernacular. You will have to determine what the truly meaningful metrics are from each package; for example: visitors versus unique visitors, and hits versus page views versus unique page views. Deriving useful information from statistics depends on your goals. If you want more viewers, and are trying to attract attention from Google searches, social network recommendations, and other external aggregators, you may be happy with an increasing number of visitors who look at only one page or spend under a minute per visit on your site. A site that aims for more discussion and community feel should have more return visitors, a longer interval between visitor entry and exit, and multiple pages viewed by each visitor.AWStats AWStats is the granddaddy of web traffi c statistics. Actually, there was a package that predated this but had many security problems, and AWStats took over as the main statistics package. AWStats is of the log parsing variety of statistics counters. It can be run on the server, or you can download the log fi les to another machine and run it if you don’t have access or permission to change the confi guration of the server running your WordPress site. AWStats requires Perl to run, and it has been used successfully on both Apache and Microsoft IIS servers, although it requires a little confi guration of the log fi le formats for IIS. To install and get AWStats up and running automatically for your site, you’ll need to be familiar with server administration tasks. As a log parsing package, AWStats is designed to run automatically in the background via a cron job on Unix systems. Because AWStats is a server-side log parsing package, it easily tracks the actual request information of your website. You can extend the information gathered by adding in the special JavaScript tag for AWStats to catch browser-side information such as screen size and browser plugin support for various technologies. One good thing about AWStats is that it is one of the original open source log parser statistics packages. It has survived so long because it is reliable and free and relatively easy to get going. This also includes many contributed scripts and tidbits of help and support from various sources around the web. Numerous hosts rely on AWStats, and like any good open source software package, there is a robust support community around it. What is not so good about AWStats is it sometimes loses track of dates, mainly because of an unin- tentional system admin error. In order to provide certain historical information and to process logs c13.indd 338 12/6/12 1:24 AM Statistics Counters ❘ 339 quicker, AWStats maintains cache fi les. If dates get out of order or other time problems exist, these cache fi les trump any new logs to be parsed and can provide inconsistent data. Basically you have to go back and rebuild all the cache fi les. Fortunately, with some searching you can fi nd some scripts to assist in this. Another complaint with AWStats is the browser agents were not updated for a long time, but this does not appear to be the case anymore. A couple of different WordPress plugins are available for AWStats, but they are not required to use AWStats on your site. One plugin for this package basically takes the human-consumable information and makes it available on the front end of your site. There is also a plugin that will add the extended information JavaScript to every WordPress page rendered so that AWStats can capture additional information. Take a look at Figure 13-1, which shows the basic AWStats reporting screen.FIGURE 13-1: Standard AWStats reporting screen c13.indd 339 12/6/12 1:24 AM 340 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAMYou can fi nd more information online at http://awstats.sourceforge.net/. AWStats is a tried and true option and is good for those sites that want to remain self-contained. Unlike examples in Chapter 11 which covered leveraging third-party content for added benefi t to your site, this option runs on your web server and keeps everything together. If you do not want to include statistics tracking JavaScript calls that make references to other sites, for performance or JavaScript avoidance reasons, AWStats is a venerable alternative.Google Analytics Google Analytics is currently the big dog in hosted web traffi c statistics. It has a clean and generally intuitive user interface for seeing the reported statistics. It works by injecting a special JavaScript tag into your rendered page, which reports traffi c and browser information to Google for parsing. And therein lies the rub with this free statistics package. You are reporting all of your traffi c information to Google. Many people use Google for nearly everything these days — e-mail, calendar, and web traffi c statistics included — although some distrust giving all this information to what could become Big Brother. While people have some trust in Google, in reality, the company could use the information they get for any number of purposes. Just think of the wealth of information Google has at its fi ngertips related to browser and OS share, and then combine this with the AdSense and keyword information from your site. Today, Google allows you to track campaigns and site “reach” by cross-referencing AdWords and AdSense traffi c with Google Analytics data. The amount of data related to website use and marketing trends is staggering. The trade-off of data access is a business decision you will have to make. Google Analytics is defi nitely marketing-oriented. Many powerful tools are built in and learning how to use them will greatly benefi t the quality of the reported data, including advanced segmen- tation of your traffi c and custom reporting data. For example, you use Google Analytics to track which specifi c PDFs from your library site get the most traffi c, and in e-mail marketing, you track which campaigns generate the most click-throughs. Many resources are available online to extend Google Analytics. For example, the following is the jQuery snippet for tracking outbound document links via Google Analytics. This code is derived from http://css.dzone.com/news/update-tracking- outbound-click./* use jquery to track outbound and file links * http://css.dzone.com/news/update-tracking-outbound-click */ $("a").click(function() { var $a = $(this); var href = $a.attr("href"); // see if the link is external if ( (href.match(/^http/)) && (! href.match(document.domain)) ) { // if so, register an event var category = "outgoing"; // set this to whatever you want var event = "click"; // set this to whatever you want var label = href; // set this to whatever you want _gaq.push(['_trackEvent'],category, event, href); } c13.indd 340 12/6/12 1:24 AM Statistics Counters ❘ 341}); var fileTypes = ["doc","docx","xls","pdf","ppt","pptx", "rtf", "txt"]; $("a").click(function() { var $a = $(this); var href = $a.attr("href"); var hrefArray = href.split("."); var extension = hrefArray[hrefArray.length - 1]; if ($.inArray(extension,fileTypes) != -1) { _gaq.push(['_trackEvent'],"download", extension, href); } });Tracking outbound traffi c is useful if you’re trying to use your site as a reference point or expertise repository, and need to know where readers are going for additional information. Getting detail on the types of documents referenced gives you a high-level view of what content fl avors are most popular or helpful. Obviously, you can add additional document types if you point users at OpenOffi ce, PhotoShop, or other fi le formats. Many WordPress plugins are available for Google Analytics, which anecdotally serves as a barom- eter for the popularity of this service. Each offers slightly different functionality, but all essentially do the same thing, which is to inject the appropriate JavaScript into the page. Some offer additional features to track the extra events via the control panel. Take a look at Figure 13-2 for a screenshot of the standard Google Analytics dashboard.FIGURE 13-2: Standard Google Analytics reporting screen c13.indd 341 12/6/12 1:24 AM 342 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAMYou can fi nd more information online at http://google.com/analytics/. For all practical purposes, Google Analytics is the de facto standard in web traffi c statistics. Nearly every site uses it to some extent. But there are alternatives if you do not want to put all your eggs in Google’s basket. Check out StatCounter (http://statcounter.com/) and Mint (http://havea mint.com/) for other options. Mint is essentially a self-hosted Google Analytics–like system. There are also emergent players such as Woopra (http://woopra.com/), which includes real-time visitor information, that are popping up from time to time.JetPack by WordPress.com We would be remiss if we did not mention JetPack by WordPress.com. This is actually a super plugin that bundles several of the WordPress.com hosting features into a single plugin for use on self- hosted WordPress sites. This plugin has many features, including social media integrations, photo gallery enhancements and, obviously, because you are in the traffi c statistics chapter, it has this functionality, too. JetPack works the same as Google Analytics — by injecting some JavaScript into your rendered HTML template and reporting back to the WordPress.com servers for tracking. JetPack is built by WordPress developers for WordPress so it has some specifi city about the way the statistics are presented with regard to posts and pages. In addition, JetPack stats are presented right in the WordPress dashboard. Although there are plugins to make other statistics packages do this through iFrames, the in-Dashboard view is the default method for JetPack. Basically, JetPack was designed from the ground up to be included in the Dashboard. For some end users, it’s nice to have everything to manage the site contained in the Dashboard, as seen in Figure 13-3.FIGURE 13-3: JetPack by WordPress.com in the Dashboard reporting screen c13.indd 342 12/6/12 1:24 AM Cache Management ❘ 343Also, for quick reference, JetPack can enable a quick view of the last 48 hours in the admin toolbar at the top of the screen. You can fi nd more information online at http://jetpack.me/. If the statistics are giving you good news — your site is gaining in popularity, readers are actively participating in discussions, and search engines are sending new users your way — you’ll likely want to turn your attention to site scalability. Now you will look at ways to improve the overall performance of the WordPress system components.CACHE MANAGEMENTWordPress is a content management system, which by its very defi nition means it creates a dynamically driven site. In today’s technology environment, that essentially means that the managed content and all of its metadata is stored in a database. Every page request has to access the database to determine which content to be displayed, versus, with a static site, simply fetching HTML fi les from the web server’s local directory. The trade-off in handing over content management to a database is that you are going to take a speed hit in the individual page access in exchange for more powerful persistence, selection, and organization tools — those features used within the WordPress core. Basic computer science comes into play here: when you introduce a new abstraction layer that’s slower than the layer above it, you typically introduce a caching mechanism as well to improve average access times. It helps to think of caching in a sequence of access methods, starting closest to the user and working back to the MySQL database. Each point in the sequence has some caching and tuning that can be done; however, like all performance tuning work, your mileage varies depending upon the access patterns, content types, and actual workload moving through that point in the system. Here is one view of the WordPress caching hierarchy that the following sections walk you through: ➤ Browser — Most of your end users’ browser performance is going to come from optimized CSS, graphics, and JavaScript libraries. Because these affect the single-page load times, we covered them in Chapter 12’s exploration of user experience. ➤ Web Server — WordPress and its plugins are largely written in PHP, an interpreted language that relies on the web server for an execution container. Improving the web server’s PHP caching will speed up some portions of the WordPress user-to-database path. ➤ WordPress Core — Caching objects used by WordPress effectively build a database results cache, the same approach taken by highly scalable, MySQL-based sites such as Facebook. Changing some dynamic page generation to static HTML rendering speeds up page access at the expense of possible small windows of update inconsistency. In addition, as we covered in Chapter 11, you can use transients to cache external or complex data for quick retrieval. ➤ MySQL — Caching objects at the database layer prevents an eventual disk access, turning a query into a memory reference where possible. These options are independent of, and frequently complementary to, enabling a caching plugin within the WordPress core.Again, the actual benefi t provided by each or any of these approaches depends on many factors, including your hosting provider’s database layer, whether you can confi gure web and database servers yourself, the size, frequency and complexity of database queries, and the overall load on your WordPress installation. c13.indd 343 12/6/12 1:24 AM 344 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAMWordPress System Complexity First and foremost, WordPress is a complex system, and honorably so. WordPress simplifi es the process of content management and broadens its core feature set through the plugin system. But providing these various hooks and fl exibility comes at the cost of database accesses, PHP processing, handling each plugin’s unique requirements, and any special theme prerequisites. Each plugin adds additional overhead to the page rendering, and the quality of code in plugins varies from author to author. Using an execution path analyzer such as WebGrind or KCacheGrind, which profi les your application to determine where bottlenecks in the code may occur, you can create a graphic representation of the complexity of a web application. Take, for instance, a plain vanilla WordPress installation using the default theme. Running a simple page load through this profi ler and viewing the resulting execution graph, you will fi nd more than 860 different functions called to render the index page, as shown in Figure 13-4.FIGURE 13-4: WebGrind visualization of WordPress complexityEven without being able to zoom in and see the details, you can perceive the inherent complexity of WordPress. Each of those functions or actions is the WordPress core gathering the necessary data for your site, including action hooks for linking in plugin and theme functionality. Each and every thing you add to your site, including that fancy theme control panel that lets you set particular runtime characteristics of your site and plugins that parse your content for related posts, creates overhead and more boxes on the execution graph. There’s no need to be alarmist here and disable plugins and choose overly simple themes. This challenge is not unique to WordPress. The fl exibility enabled through WordPress, especially the confi gurable runtime fl exibility of WordPress, which is so powerful, is an expensive operation. The alternative is a statically fi xed set of features that require new built-in code to accomplish new features, rather than the versatile plugin architecture of WordPress. Each of those plugins and theme hooks adds functionality and features to your WordPress installation. That is why you enabled them in the fi rst place. Just accept that it is a trade-off in features versus performance, some negligible and some larger. In practice, your site does not really change that often. You are probably not running the next Twitter through a WordPress installation (although you can build a reasonable facsimile with the p2 theme) and the content does not change every 30 seconds. Leveraging the ideal situation in which c13.indd 344 12/6/12 1:24 AM Cache Management ❘ 345 your content is viewed signifi cantly more frequently than it’s updated, and allowing for minor windows of inconsistent updates, you will now look at caching layers from the web server back to the MySQL installation.Web Server Caching and Optimization Improving WordPress scalability through the web server layer involves PHP execution optimization and web server confi guration changes. In both cases, you’ll need administrator-level access to the web server confi guration fi les. You will work your way back to the MySQL queries and object caching, but no matter how you end up with a list of pages, WordPress relies on PHP to pull the displayed page together and generate its HTML. PHP is an interpreted language. That means for every execution of the code, the code must be interpreted and compiled to machine code that a computer can use. This methodology has pros and cons, and the fl ame war that would ensue is completely outside the scope of this book. However, you can cache at the PHP execution level with an opcode cache. A PHP opcode cache attempts to bridge the gap between runtime interpreting and full-on compiled code. APC (or Alternative PHP Cache) is one such implementation that works to cache and optimize the intermediate PHP code. This method is completely outside of WordPress and works on the underlying PHP layer of your server, making the actual confi guration outside the scope of this book. To get APC set up, you will need full access permissions on your server. Once APC is set up, it caches the compiled PHP fi les that make up the WordPress core. The biggest downside is that you have to restart the server every time you change a PHP page. If you are making theme changes, this means a restart each time you modify a template fi le. You can find more information about APC at http://us3.php.net/manual/en/book.apc.php. Again, the ability to enable APC and start/stop the web server depends on whether you having suffi cient administrator privileges.Caching can be further augmented by using memcache and memcached, both of which require server administration level of implementation. Memcache uses your server’s RAM to cache frequently used objects. RAM is signifi cantly faster than fi le-based operations, and because memcached runs as a local daemon, it is also completely outside of your web server. You can fi nd more information about memcache at http://us3.php.net/manual/en/book.memcache.php and http://memcached .org/. The key benefi t provided by these in-memory systems is to add another layer of caching between WordPress and the MySQL database. As discussed in Chapter 6, WordPress caches the last results retrieved via SQL queries on its MySQL database, but if your site is consistently loading and then fl ushing the cache as users navigate between several popular sections of the site, this additional layer of caching will improve performance by keeping the result sets of several recent queries in memory. What’s happening under the hood is that the WordPress object cache is mapped to objects managed by memcached, allowing repeat queries to be satisfi ed out of the cache rather than through another SQL query to the database. This level of caching is the PHP code level caching allowing the PHP runtime to short-circuit previously cached information. As you’ll see there are many locations in the execution pipeline where caching can be enabled. While you are considering the PHP level of the WordPress stack, you should also optimize (and secure) your php.ini confi guration. PHP has prospered by having so much built-in functionality that it lowers the barriers of entry and empowers developers to just get the task done. This has been c13.indd 345 12/6/12 1:24 AM 346 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAM the boon and the bane for PHP. Take a look at your php.ini fi le and disable extensions you are not using. You can always turn them back on if you need them in the future. Also take this opportunity to secure your PHP execution container and help it run faster. Here are some simple settings. There are probably more, depending on your setup, which you can likely turn off to improve security and performance:;Hide PHP for security expose_php = Off ;Turn off for performance register_globals = Off register_long_arrays = Off register_argc_argv = Off magic_quotes_gpc = Off magic_quotes_runtime = Off magic_quotes_sybase = OffFinally, on the system administration level, optimize your web server. In most cases, the stock confi guration for your web server is designed to handle the most common basic use cases. Certainly, it has not been tweaked to match your specifi c server’s capabilities. Apache, for example, comes with tons of extra modules to handle general-case situations. If you do not use those modules, disable them. This will reduce the overall memory footprint of Apache. In practice, it has been possible to tweak Apache to perform better under restricted resources (such as low-memory virtual private servers) by adjusting the Apache PreFork confi guration. The default confi guration is pretty generous, and depending on your site’s traffi c and system confi guration, you can usually pare this down. For example, on a low-traffi c site hosted on a low-memory shared server, you could edit your Apache2 confi guration fi le to the following, assuming you are using Apache2:<IfModule mpm_prefork_module> StartServers 3 MinSpareServers 3 MaxSpareServers 3 ServerLimit 50 MaxClients 50 MaxRequestsPerChild 1000 </IfModule>These settings are for a relatively low-traffi c site on a low-memory server. Your results will vary, but these changes anecdotally affected the web server’s response time for your WordPress installation. Of course, you will have to adjust these settings to meet your own requirements. Realize that the LAMP stack has become so popular because often it just works when you install it. That is because the default confi gurations are general-purpose setups designed to work across a broad spectrum of situations. You will need to adjust the confi gurations to optimize to your specifi c situation when the time comes. Tuning the individual components of the LAMP stack warrants a book unto itself. Like WordPress, the LAMP development stack is very popular because of its fl exibility and capability to handle a multitude of different tasks. The management and administration of LAMP components are c13.indd 346 12/6/12 1:24 AM Cache Management ❘ 347 required skills for the full stack solution developer. Invest some time learning your tools and how to deploy them effectively.WordPress Object Caching The goal of web server caching is to keep frequently accessed fi les and popular chunks of code in memory and ready to serve or execute. Within WordPress, caching has to deliver a request for a page without going through additional code or database accesses, which really boils down to short- circuiting the PHP WordPress core and serving up a static representation of your page directly. Object caching keeps certain frequently used and expensive data sets in memory. This is very similar to the transient cache discussed in Chapter 11, but while transients are set by you, the developer, object cache is set by the WordPress core. The fl exibility of object caching means that when certain information does change, that does not affect the entire cache, but only the objects in the cache that actually changed. However, object caching still requires the plugin to execute PHP to determine which aspects of the cache are still valid and also for WordPress to execute the PHP to pull the parts of the page together for rendering. As previously discussed, optimizing your web server’s PHP environment and enabling WordPress level object caching are quasi-independent as a consequence. There may be times when your content is static enough, or being served so frequently, that you need to short-circuit the whole PHP and object cache overhead — for example, when your page is being listed in the top echelons of Reddit and Slashdot. A good way to do this is to have your page rendered to static HTML and served directly by the web server. After all, this is what the web server was designed to do in the fi rst place. In our opinion, the best plugin for this is WP-Super Cache by Donncha O Caoimh. WP-Super Cache is based on and an improvement of the WP-Cache plugin. (See, this one is SUPER!) WP-Super Cache functions in various modes, including writing out static HTML fi les. However, it does require mod_rewrite for the static HTML fi les, so this plugin will only work on Apache servers. WP-Super Cache has an extensive control panel that allows the site administrator to adjust the settings to meet specifi c needs. It even includes a full lockdown mode that prepares for a heavy traffi c spike. Other caching plugins such as W3 Total Cache are also viable options. Many caching plugins build on the basic theme of generating HTML for a page and caching it with the URL used to access the page as a key. Each plugin will have variations on cache invalidation and page lifetime policies, and all of them disrupt the general dynamic nature of WordPress page generation. If you’re going to change your theme, add new plugins, or otherwise alter the fl ow of data from MySQL to the user’s browser, either disable WordPress caching until you’re sure all of your changes work, or frequently invalidate and fl ush the cache so that you can see the freshly generated pages as you test.Transient Caches Chapter 11 covered transient caches but they are touched on again here. Transient caches are developer-defi ned caches that you set up in your code. These are commonly used for storing remotely fetched data in your local site for repetitive reuse. This was the primary case for them in Chapter 11. c13.indd 347 12/6/12 1:24 AM 348 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAMAnother use for transient caches is to store complex computed data. For example, you might have a function in your functions.php template that does a complicated query across your entire WordPress Multisite network to generate a network-wide navigational aid. This data likely does not change very often, but the computation of the query is signifi cant enough that it may slow down page rendering. With a transient cache, you can perform the complicated query and store it in a transient cache so the next visitor does not have to wait for the SQL query to execute. Using a transient in this nature improves site performance by reducing the queries to the database.MySQL Query Cache While conducting research for this book, we (the authors) set up a stock WordPress installation using the Twenty Eleven theme and no additional plugins — essentially an out-of-the-box installation. To render the index page, WordPress used more than 20 MySQL queries. Try it yourself by adding these two PHP lines to your footer.php template fi le:<?php echo get_num_queries(); ?> queries. <?php timer_stop(1); ?> seconds.Reload your page and you will see the number of queries and the time it took at the bottom of your page. You have to evaluate your site, but odds are the database-persisted content is not changing quickly enough that you need to make all these database calls for every page load. The translation of a URL into a MySQL query was covered in Chapter 5, and Chapter 6 looked at the underlying data models, so the volume of database traffi c required for the basic index page shouldn’t be too surprising. WordPress caching improves access times to content extracted from MySQL. If you want to further improve MySQL performance and make it more responsive to queries from the WordPress core, you’ll want to explore the MySQL query cache. The MySQL query cache stores the results of select statements, so that if an identical query is submitted, the already retrieved results can be immediately pulled from the system RAM and returned. This will signifi cantly increase your response time, as long as your data is not changing that much; under higher rates of change you may not see the updates immediately. To enable the MySQL query cache, you will have to edit your MySQL confi guration fi le on the server, assuming you have adequate permissions at your hosting company to do so. If you edit your MySQL confi guration fi le, you can raise the memory limit. For example:# enable 16 MB cache query_cache_size = 16MBe careful not to go overboard here. Allocating too much RAM to MySQL caching will adversely affect other subsystems on your server. It is always a balance. Even just enabling this cache creates a management overhead in MySQL, but generally speaking, this trade-off works in your favor. c13.indd 348 12/6/12 1:24 AM Load Balancing Your WordPress Site ❘ 349LOAD BALANCING YOUR WORDPRESS SITEAt some point, you (let’s hope) hit the performance limit of a single software stack on one physical server. That’s when you may want to load balance your WordPress site with one or more additional servers. You may decide to add servers either for scalability to handle more requests, or as a failover precaution to increase the availability of your site. Whatever the reason, load balancing your site gets you both of these features, but it is a complex issue. Now you will briefl y consider some of the challenges you will encounter when attempting to load balance a dynamically generated site. First and foremost, you need a means to load balance. The simple approach of using round-robin DNS to bounce successive HTTP requests between your servers as needed will cause problems, especially with session cookies. You will need a legitimate load balancer to handle this. The load balancer could be a software package such as Pound (http://www.apsis.ch/pound/) or a full hardware solution such as an F5 BIG-IP (http://www.f5.com/products/big-ip/). Both will handle the session stickiness and load balancing for you. The second challenge is keeping your dynamic data in synchronization between your two (or more) web front-ends. Consider that your site administrator could effectively log in to either web front- end, post new content, and upload a graphic asset to the uploads directory. However, the next request could be load balanced to the other server, where this content may not exist. Look at the uploads directory fi rst. This content is uploaded from the WordPress Dashboard to the uploads directory of that WordPress installation. By default, content is uploaded into /wp-content/ uploads/. However, you can change the uploads directory in your Settings ➪ Media Dashboard. Depending on where you set your uploads folder, you could also reap the benefi t of having shorter asset URLs. At this point you have options. One option is to have a shared folder that both web servers can access. Most likely this would be an NFS/Samba share on a third server, which serves as your MySQL server. A second option is to use rsync or a similar tool to coordinate uploads between the two servers and make sure each has the same assets in place. Using the shared folder makes the assets immediately available, but introduces a single point of failure. Alternative, rsync’ing the assets to multiple locations replicates the data, removing a single point of failure, but introduces a time delay on when the asset is available at the remote locations. Pick your poison depending on your needs. The second challenge is your dynamic data that is stored in the database. Assuming your database is not the bottleneck and the reason for load balancing, you could use a third server as your database server. Both web servers can then read and write from the same source. This can be a more secure deployment architecture when your database server is not directly addressable on the public Internet, but it also creates a potential single point of failure. Technically, you are only load balancing the front-end web servers in this situation. Adding a second database server increases the redundancy but introduces the problem of keeping two MySQL database tables in synchronization. MySQL servers can be confi gured for replication in a master-slave setup. Technically, this again is not load balancing because only one server is being accessed at a time, but this type of confi guration does provide additional redundancy. Changes to the master MySQL database are replicated to the slave database in near real time via a journaling log. Should the master database fail, the slave has a full set of data for a manual cut over. c13.indd 349 12/6/12 1:24 AM 350 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAMFinally, there is also a special WordPress-specifi c solution for multiple database servers. HyperDB (http://codex.wordpress.org/HyperDB) was created by Automattic to handle the requirements of WordPress.com traffi c. HyberDB is a full replacement for the built-in WordPress database access layer and includes functionality for using multiple databases, sharding or partitioning your database across multiple servers, and also replication and tiered failover. Unfortunately, the documentation is far from complete. As you can see, load balancing for performance and high availability is an extremely complex topic. There are countless variations of systems in place to handle a vast expanse of needs and requirements. This short overview of the topic certainly skirts over many nuances and challenges being faced when deploying WordPress into a high-availability environment. <a href="/tags/Cloud_computing/" rel="tag">Cloud computing</a> and content delivery networks are hot topics right now, and you should expect to see WordPress utilizing these services for critical aspects and redundancy as those technologies and services mature.DEALING WITH SPAMAs your WordPress site gets noticed and generates traffi c, it becomes a natural target for spammers. If you’re noticing posts on your site that you don’t expect, or see users in the Dashboard that you didn’t create, you have other security problems that are covered later in this chapter. Most likely, your posts will accrete a variety of spam comments as a side effect of being popular. You can recognize spam by a list of links within the comment, or content-free comments saying that the poster enjoyed your writing, with an attached URL or source address that invites you to a less-than-reputable destination. In either case, the goal of comment spam is to generate more <a href="/tags/Web_content/" rel="tag">web content</a> that points back to the spammer’s site, taking advantage of the page popularity ranking algorithms used by Google and others that give weight to incoming links. The best way to deal with spam is to simply get rid of it, denying spammers the opportunity to use your site to boost their own visibility. There are three basic approaches to dealing with the problem: make it impossible for anyone to leave comments, increase the diffi culty of a spammer sneaking a comment onto your site, and enable auto-detection of common spam patterns. Obviously, disabling comments (through the Dashboard) is a bit harsh and defeats the goals of establishing conversation with your readers. On the other hand, if you decide to take this drastic step, remember that changing the settings for posts on the control panel affects future posts only; anything already on your blog will still have comments enabled unless you go through the Dashboard and turn them off individually. If you don’t mind an even greater bit of brute-force effort, you can remove the wp-comments.php fi le from the WordPress core, which somewhat unceremoniously puts an end to the ability to comment on your posts. We recommend something a bit more subtle.Comment Moderation and CAPTCHAs One approach to comment spam is to slow down the spammers; this simple approach, however, slows down valid commenters as well. You can require commenters to register as site users before being allowed to post comments, as discussed later in this chapter, but that has the downside of preventing passing-by users from adding their thoughts. It also requires that you stay on top of the user c13.indd 350 12/6/12 1:24 AM Dealing with Spam ❘ 351 registration, as you may see seemingly valid users that are created purely for the purpose of posting spam to your blog. Moderation is another tool in the slow-but-don’t-stop vein; you can hold all comments for moderation or require all commenters to have a previously approved comment. In effect, you’re putting the burden of spam detection on yourself, looking at each comment as it appears and deciding whether to post it to your site or fl ush it. Again, an innocuous looking comment may be the approval step- ping stone for an avalanche of spam later on from the same user. As with many security mechanisms, the bad guys are continually getting smarter and more automated, and testing the edge protection and response of the systems they want to infi ltrate. A variation of the brute-force and moderation method is to blacklist IP addresses that seem to be the primary sources of spam; the access controls can be put in your .htaccess fi le. Again, this is perhaps a bit like hunting bugs with an elephant gun, as you’re likely to block valid IP sources from common carriers who are unfortunately home to some low-limit spammers. Also, spammers jump IP addresses easily using botnets and other resources, so this can be a never-ending war that you cannot keep up with. Enter CAPTCHA methods — based on a phrase coined at Carnegie Mellon University that osten- sibly stands for “Completely Automated Public Turing test for telling Computers and Humans Apart” — that impede spammers’ ability to post unwelcome comments by requiring them to enter some additional, dynamic piece of information. There are quite a few CAPTCHA-generating plugins for WordPress, all of which add a displayed word or math problem to the end of the comment posting form, requiring the user to enter the correct information before the form is submitted. The simplest of these, the Math Test plugin, displays a two-term addition problem that must be solved by the user. The basic idea is that an automated spamming process won’t be able to recognize the distorted words or solve the problems, alleviating the spam at the point of insertion. There’s some debate as to the effectiveness of CAPTCHAs, with their failure rates suggested to be as high as 20 percent. You’re also adding a step for commenters, albeit a trivial one. If your site attracts a large, non-English speaking audience, CAPTCHAs depending upon wavy English words will be effective, but only in preventing valid comments from frustrated users. The WP–Spam free plugin is an inverse CAPTCHA; it tries to ensure that the commenter is using a browser, and not coming in via an automated process. This combination of JavaScript tricks is a variation on the spam impedance theme, and like the others, its effectiveness and user impact will vary depending upon the demographics of your site viewers.Automating Spam Detection The fi rst step in automating spam detection is blacklisting certain types of posts or particular words. In the Dashboard, choose Settings ➪ Discussion in the Comment Moderation box, you’ll fi nd an option to block any comment that contains more than a particular number of links. Don’t set this to zero, or anyone who includes his own site URL in a comment is going to be fi ltered. This cuts down on the obvious spam messages, however. Similarly, adding words to the blacklist like “Vicodin” will eliminate the faux-pharmacy spam, but if you’re perturbed by offers of fake Rolexes, don’t add “watches” to the blacklist or you’ll drop any comment that uses “watches” as a verb as well as a fake product noun. Word blacklists are universally effective in blocking comments with those words, irrespective of context. c13.indd 351 12/6/12 1:24 AM 352 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAMFortunately, WordPress has the Akismet plugin built in for dealing with comment spam that relies on a crowd-sourced blacklist and is transparent to users. Go to http://akismet.com/ to register for an API key for the service; when you open up the Dashboard and confi gure the Akismet plugin, you’ll need this to make sure your instance of WordPress can connect to the Akismet service. Effectively, Akismet takes each comment as posted, runs it through a database of spam comments hosted by Automattic, and decides whether or not to mark the comment as spam. Statistics on the akismet.com site claim that upwards of 80 percent of all comments are spam, and that they have caught and marked more than 55 trillion spam comments. There are other implementations of the Akismet service besides the built-in plugin, and Akismet works on other content management systems as well. Akismet is priced based on the size and type of your site, ranging from free to $50 per month. While the freely available nature of WordPress and most of its related plugins and themes has been highlighted, paying for Akismet spam protection is also highly recommended. Compared to the cost of a commercial WordPress hosting option, most low-end Akismet plans are minimal in cost. You remove a time-consuming administrative burden from your plate for a few dollars a month.SECURING YOUR WORDPRESS SITEUnfortunately, with success and popularity you also become a target. WordPress is a successful and popular platform for websites and with that brings the attention of the hackers and bad guys. It is simple economics that bad guys looking to build a network of sites will look to the most widespread applications and attack their vulnerabilities. Unfortunately, one of the vulnerabilities with WordPress (similar to PHP) is that, because of the low barrier of entry and ease of use, users who are generally not too tech savvy or security minded can utilize WordPress without recognizing the full security ramifi cations involved. This portion of the chapter covers some of the basic security principles you should employ when using WordPress. Some of them seem like common sense, but surprisingly are not put into practice on the average site. These are all preventative measures that you need to put into place before you really need them. As Benjamin Franklin said, “An ounce of prevention is worth a pound of cure.” The time you spend protecting yourself will pay off should you have to work on cleaning up an exploited website.Staying Up-to-Date Rule number 1 is to always stay updated. WordPress developers are constantly working to make WordPress a better, more secure, and stable platform. This is one of the key advantages to open source software. Many developers, each with different skill sets, are looking over the code every day and performing various audits and updates to improve the overall codebase. Updates often fi x security concerns before there are exploits in the wild. Generally, exploits have been targeting outdated versions of WordPress while consistently updated sites are immune. WordPress implemented new notices in the Dashboard letting you know when there is a new version available. Another new feature is the ability to upgrade WordPress directly from the Dashboard. c13.indd 352 12/6/12 1:24 AM Securing Your WordPress Site ❘ 353The WordPress team has been working to make upgrading as painless as possible. This new feature lets the site administrator update the WordPress core right from inside the web interface. If your web server has the ability to write to the fi les in your WordPress directories, then the automatic upgrade functionality works. If not, WordPress prompts for your FTP credentials to update the fi les for you. Both of these situations are of concern. In general, your web user should not have write permissions to your entire web root. This is just asking for trouble, especially on a shared hosting platform, excepting, of course, certain directories such as the uploads folder that must be writable by the web user in order to function. Second, it is not clear how this FTP credential information is stored or used. Although it is unlikely anything nefarious is happening, users are not encouraged to key in FTP (an unsecured protocol at that) credentials into any form that asks for it. However, if you do decide to go this route, you can set some WordPress confi guration variables in your wp-config fi le that will further automate the FTP process. There is defi nitely a balance here between the simplicity of keeping the WordPress core updated, which is of the utmost importance, and with keeping the web root security intact. Another feature is the update notices in the Dashboard and changelogs. The notices alert you to pending updates to WordPress core, themes, and plugins that you have installed. Many of these updates include changelogs that let you keep tabs on what is actually changing in the new version. This can help you make a decision on if the update is critical and needs to be performed immediately, or whether it can wait until a scheduled maintenance window. It is up to the developer to keep the changelog information current. Hiding WordPress Version Information This section is about concealing which specifi c version of WordPress you are running from the public eye. Honestly, there are mixed opinions on this. WordPress evangelists would say leave it in there. Say it loud and say it proud. On the other hand, security-conscious users would say take it out. It is a way for the bad guys to easily fi nd vulnerable sites, so why give it up? Then again, the WordPress developers have a good point. For a botnet scanning for vulnerable sites, it does not make sense to waste time looking for specifi c WordPress versions, when a botnet can just run the attack against the site. It will take the same amount of time, so why take twice as long? If you are going to get hacked because of your old version of WordPress, hiding the version number is not going to stop it. You should have been upgrading anyway. In a standard WordPress installation, the version number is shown in the HTML source code as a meta tag for anyone to view the source and see. However, if you want to remove this meta tag, there are several plugins that can do it for you. Or you can edit your functions.php fi le and at the bottom add the following:Remove_action('wp_head', 'wp_generator');Also, be on the lookout for certain themes and plugins that include version information in your header. c13.indd 353 12/6/12 1:24 AM 354 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAMLimit Login Attempts Further precautions include limiting the number of login attempts on your WordPress control panel. This can prevent or discourage bad guys from brute-force attacking your site. By default, WordPress will allow unlimited invalid login attempts, meaning that an automated script could be whacking away at your site all day long. The Limit Login Attempts plugin by Johan Eenfeldt looks to remedy that. After a confi gurable number of invalid login attempts, that IP address is locked out for a specifi ed period of time. This slowdown reduces the attractiveness of your site to an automatic attack script. You can fi nd more information about Limit Login Attempts at http://wordpress.org/extend/plugins/ limit-login-attempts/.Using Good Passwords Furthermore, use good passwords for your account. Not just your WordPress accounts, all of your online accounts. Yes, we all have hundreds of passwords to remember, but there are tricks to using good passwords, including mnemonics and password safes. WordPress has a nice JavaScript indica- tor when you are setting your password to let you know the quality of it. Remember that you can pick a good password that is something you remember, or use a secure password-safe application to store it. Your password is your key to your kingdom, so make it a good key.Changing Your Table Prefi x This is another method to obscure the default attack vector. By default, new WordPress installations have a table prefi x of wp_. That means every table in your WordPress database has a very predictable name, making it easier for attackers to form an assault on your site. If you are deploying a new site, set something unique for this prefi x. If you are already on an existing site, plugins are available that can handle renaming your tables for you. The WP-Security Scan by Michael Torbert, which is covered later in this chapter, offers the functionality to change your table prefi xes for you. Make sure you make a database backup before performing this task because the implications if it does not work are quite severe. Moving Your Confi guration File By default, the WordPress confi guration fi le is located in the root of your website. In the event that PHP stops functioning on your web server for any reason, you run the risk of this fi le being displayed in plaintext, which will give up your passwords and database information.You can safely move the wp-config directory up out of the root directory. This will stop it from ever being accidentally served. WordPress has built-in functionality that will automatically check the parent directory if it cannot fi nd a confi guration fi le.In some situations on certain hosts, this is not an option. An alternative is to set your .htaccess to not serve up the wp-config fi le. Add the following line to your.htaccess fi le in the root directory:<FilesMatch ^wp-config.php$>deny from all</FilesMatch> c13.indd 354 12/6/12 1:24 AM Securing Your WordPress Site ❘ 355Moving Your Content Directory Since WordPress 2.6, you can move your wp-content directory. This way, you can take a large portion of your WordPress installation and move it to a non-default location. Again, this makes hoops for the bad guys to jump through, hopefully discouraging them.Make two additions to your wp-config fi le: define('WP_CONTENT_DIR', $_SERVER['DOCUMENT_ROOT'].'/mysite/wp-content'); define('WP_CONTENT_URL', 'http://example.com/mysite/wp-content');Some plugins may have diffi culty dealing with a nonstandard directory structure. If you are expe- riencing problems with certain plugins, you can add the following lines to your wp-config fi le for compatibility: define('WP_PLUGIN_DIR', $_SERVER['DOCUMENT_ROOT']. '/mysite/wp-content/plugins'); define( 'WP_PLUGIN_URL', 'http://example.com/mysite/wp-content/plugins');Moving your content directory does not in and of itself make your site more secure. What it does is prevent the automated tools used by attackers from working on your site. These automated tools are looking for the least common denominator of sites; so essentially, they are looking for stock WordPress confi gurations with default settings because that will give them the most bang for the buck. Security through obscurity is not security, but it does make your site a less attractive target.Using the Secret Key Feature In your WordPress config fi le are secret key values for encrypting user cookies. There are four keys (since WordPress 2.6) to establish the secret, or private, key used by WordPress to protect session information stored in user cookies. Each key also has a “salt value” that is used by the cryptography functions to reduce the likelihood that a directory-based attack would discover a password through brute-force. A potential attack would have to start with both the guessed password and the salt value. If you don’t specify salt values, WordPress generates them. You should set both the secret keys and salt values to make the encryption of user session data for your site stronger. Either make them up or visit https://api.wordpress.org/secret-key/1.1/ salt and get randomly generated ones. You can change these keys at any time, but it will force anyone who is logged in to log in again. define('AUTH_KEY', 'C?m92_K%B[7,,Onl(&WG,oodC9ue1y;aUK[e,.E+([Y?0D+/ ]i*!PkF?I:U+C^6'); define('SECURE_AUTH_KEY', 'oesV)E.Z<y@o.o1eM|c@7)t^SL:06WjDENo;t_j.e4(eX@8#`~gy1S&R*Gf!k19+'); define('LOGGED_IN_KEY', 'Y?fgU+EleuDKE3n-^~cF%IbgTR,ep+UZE={>8,j,EO+7a-u|c]EH;|G@|4ZS#a+-'); c13.indd 355 12/6/12 1:24 AM 356 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAM define('NONCE_KEY', 'g6f<q6QB| 1u59Q]~(r1B@<dl2f]rkQVg7HMx}!B#OzPPyG[.N{RV<yA2l+=.r7#'); define('AUTH_SALT', '}e@Vd[W0d}?u&Ps>MyO1NZT>tU[Kg4QW%+y-fyRU|d-PWAV7az+a0K6qx-{iwSv)'); define('SECURE_AUTH_SALT', '9Nbtg_v1D}?f/rj*/p;a[)}jq-y&YVxqA6.KSk;am:sjH}-!uN6n5]i?NIuW&9<l'); define('LOGGED_IN_SALT', 'pQ;TXDxRN`TmDl$+gU0EgG-1OMYM*[p6R}07)7Fs*/%Yec]t|E+piqLf1.t2kLTc'); define('NONCE_SALT', '~<A7*5IS&N:Gy!:yYM`LuggB0^1RIjSy:QEOP@.TZs!Dq-73i3KQYa:3j1WYIeUg');Do not use these values; set up your own.Forcing SSL on Login and Admin You can force your visitors and administrators to log in via an SSL-encrypted page, assuming you have that set up already. Edit your WordPress config fi le and add the following fl ag: define('FORCE_SSL_LOGIN', true);You can also force the entire WordPress Dashboard to be served over HTTPS. Again, edit your config fi le and add the following line: define('FORCE_SSL_ADMIN', true);Please do not just blindly enable these features. This can be problematic if you are using a self- signed certifi cate on your site. Note that WordPress likes to build internal post links using the URL that you are accessing the Dashboard with. So, if you forced SSL on the Dashboard and are using a server self-signed certifi cate, the internal post URLs will do the same and your visitor will be have to accept the certifi cate also. Generally, this is not a good practice. Work with your hosting provider to obtain a certifi cate from a respected certifi cate provider.Apache Permissions Permissions will vary depending on your confi guration, but a good rule of thumb is to set fi les to 644 and folders to 755. If you cannot upload to the uploads folder, adjust those privileges alone. Generally, the fi les are set to be in the same group as the web server and owned by the local user. For example: drwxr-xr-x 8 ddamstra www-data 4096 2012-09-02 16:34 . drwxr-xr-x 8 ddamstra root 4096 2010-12-18 20:39 .. -rw-r--r-- 1 ddamstra www-data 9835 2011-03-15 13:17 apple-touch-icon.png -rw-r--r-- 1 ddamstra www-data 41662 2010-12-07 15:04 favicon.ico -rwxrwxr-x 1 ddamstra www-data 3456 2010-12-07 14:51 .htaccess -rw-r--r-- 1 ddamstra www-data 395 2012-09-02 16:34 index.php -rw-r--r-- 1 ddamstra www-data 9177 2012-09-02 16:34 readme.html -rwxrwxr-x 1 ddamstra www-data 1137 2011-07-13 09:07 sitemap.xml -rwxrwxr-x 1 ddamstra www-data 514 2011-07-13 09:07 sitemap.xml.gz c13.indd 356 12/6/12 1:24 AM Securing Your WordPress Site ❘ 357 drwxr-xr-x 6 ddamstra www-data 4096 2012-09-02 16:35 .svn -rw-r--r-- 1 ddamstra www-data 4264 2012-09-02 16:34 wp-activate.php drwxr-xr-x 10 ddamstra www-data 4096 2012-09-02 16:34 wp-admin -rw-r--r-- 1 ddamstra www-data 1354 2012-09-02 16:34 wp-app.php -rw-r--r-- 1 ddamstra www-data 271 2012-09-02 16:34 wp-blog-header.php -rw-r--r-- 1 ddamstra www-data 3522 2012-09-02 16:34 wp-comments-post.php -rw-r--r-- 1 ddamstra www-data 3177 2011-02-24 09:15 wp-config-sample.php drwxr-xr-x 7 ddamstra www-data 4096 2010-11-30 15:57 wp-content -rw-r--r-- 1 ddamstra www-data 2726 2012-09-02 16:34 wp-cron.php drwxr-xr-x 9 ddamstra www-data 4096 2012-09-02 16:34 wp-includes -rw-r--r-- 1 ddamstra www-data 1997 2011-02-24 09:15 wp-links-opml.php -rw-r--r-- 1 ddamstra www-data 2341 2012-09-02 16:34 wp-load.php -rw-r--r-- 1 ddamstra www-data 29084 2012-09-02 16:34 wp-login.php -rw-r--r-- 1 ddamstra www-data 7712 2012-09-02 16:34 wp-mail.php -rw-r--r-- 1 ddamstra www-data 9916 2012-09-02 16:34 wp-settings.php -rw-r--r-- 1 ddamstra www-data 18299 2012-09-02 16:34 wp-signup.php -rw-r--r-- 1 ddamstra www-data 3700 2012-09-02 16:34 wp-trackback.php -rw-r--r-- 1 ddamstra www-data 2788 2012-09-02 16:34 xmlrpc.phpNote that this will most likely break some of the cool functionality such as one-click upgrades, and theme and plugin installations from the control panel. In this case, you may have to provide WordPress with the FTP credentials to your site for this functionality to return. See the section, “Staying Up-to-Date,” in this chapter for more on why this is a concern.MySQL Credentials Set your MySQL login and permissions correctly. For the love of all things open source, do not connect your WordPress site to your database with the MySQL root user. Set up a special user for each WordPress site. Make sure it only has access to the database it needs, and make sure it only has the privileges it needs. For example, your WordPress database user never needs to grant access to another user.Recommended Security Plugins Being vigilant is an important step in security. You cannot expect what you do not inspect. That is, you cannot expect things to be working, if you do not check in on them periodically. Some plugins help with security maintenance and confi guration on your WordPress installation. Just like anti virus and malware detection on workstations, these tools are here to assist in strengthening your security posture.WP-Security Scan WP-Security Scan by Michael Torbert, shown in Figure 13-5, provides an overall security scan of your WordPress installation. It checks many of the items listed previously, including WordPress version, table prefi x, and absence of the admin account. It also includes a fi lesystem scanner to verify that the permissions are set to the recommended settings. WP-Security Scan provides a nice mechanism to make sure the base settings are in line with a good security posture. We look forward to Torbert adding new features in future releases. c13.indd 357 12/6/12 1:24 AM 358 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAMFIGURE 13-5: WP-Security Scan resultYou can fi nd more information on WP-Security Scan at http://wordpress.org/extend/plugins/ wp-security-scan/.WordPress Exploit Scanner WP-Exploit Scanner is another plugin by Donncha O Caoimh. The Exploit Scanner scans your fi les, posts, and comments for suspicious information. Basically, this is a forensics tool for you to use to make sure your site has not been compromised. This plugin does not remove anything but it creates a list of suspicious content for you to review. The challenge here is that even with the fi ltered list, you have to have some idea what you are looking for. Running this plugin may result in false posi- tives related to JavaScript from plugins and the WordPress core fi les.You can fi nd more information about the WordPress Exploit Scanner at http://wordpress.org/ extend/plugins/exploit-scanner/.WordPress File Monitor The WordPress File Monitor plugin by Matt Walters, shown in Figure 13-6, looks for fi les in your WordPress installation that have been added, changed, or deleted. The plugin can be confi gured to send an e-mail should any fi le system activity occur. In addition, this plugin can be set to exclude certain directories, such as the uploads folder or fi le-based cache folders. c13.indd 358 12/6/12 1:24 AM Securing Your WordPress Site ❘ 359FIGURE 13-6: WordPress File Monitor alertIf fi le system changes are made, this plugin sets a warning in your WordPress Dashboard and also sends you an e-mail to alert you of the changes. This can be very handy in the event that something bad happens but will also trigger false alarms when you are performing updates. It is assumed that you know when you are doing updates and therefore can weed these out.You can fi nd more information about WordPress File Monitor at http://wordpress.org/extend/ plugins/wordpress-file-monitor/. This plugin has not been updated in a while, but we continue to use it on our non-Multisite sites.WordFence Security WordFence Security by Mark Maunder is a comprehensive security plugin. This plugin checks your installed core fi les against the current revision in the WordPress repository. It checks both your core WordPress fi les as well as plugin fi les. Whereas the WordPress File Monitor is looking for new fi les added to your site root, potentially dropped in by bad guys, WordFence Security is evaluating your core and plugin fi les for changes or variations from the source code. WordFence also scans your actual content for malware and phishing signatures as seen in Figure 13-7, and it has many other security features covering a large spectrum of potential threats or attack vectors. c13.indd 359 12/6/12 1:24 AM 360 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAMFIGURE 13-7: WordFence Scan ResultsOne of the more interesting features of WordFence is the live traffi c information that ties into a software-level fi rewall. Using the live traffi c and fi rewall features, you can block specifi c IP addresses or countries from accessing your site. This can help when an attacker is attempting to compromise your site. Furthermore, you can confi gure WordFence to automatically block or throttle access for IP addresses when usage from those traffi c sources exceeds limits that you set.You can fi nd more information about WordFence Security at http://wordpress.org/extend/ plugins/fence/.USING WORDPRESS ROLESAny smart manager learns how to delegate work, and a site manager should also learn this important skill. The WordPress role system allows you to assign different privileges to different user accounts. WordPress’s default roles cover the basics and start to establish a publishing workfl ow through the fundamental capabilities of each role. These can be further extended through various plugins to create new roles with additional capabilities for specifi c tasks. If you are the only person managing your site, you probably do not need roles. It boils down to you, the site administrator, and them, the unregistered masses. This setup, with no ability for a new user c13.indd 360 12/6/12 1:24 AM Using WordPress Roles ❘ 361 to register, is a secure way to operate your site. But it also discourages participation. Eventually you may want to open it up to allow regular visitors to log in and reap some additional ease-of-use benefi ts. You assign roles to users in the user management dashboard. Each user must be assigned to a role, and your site will have a default role for registered users. Setting each of these appropriately in the Dashboard depends on your actual needs and the security permissions you need to delegate.Subscriber Role The Subscriber role is essentially the same as a non–logged in visitor. So why do you need it if this person can read posts and post comments the same as a guest visitor? You may need the Subscriber role for a couple of reasons. First, you may want to allow this role for regularly returning visitors. If they are registered, they get some advantages such as not having to fi ll out all the fields to post a comment each time. Second, as a spam control measure, you may only allow registered Subscribers to post comments. This will weed out many of the automated spam- bots. Finally, certain plugins require this base level for functionality.Contributor Role The next step up is the Contributor role. The Contributor role is the fi rst step in delegating respon- sibilities to your site users. The key privilege for Contributors is they can create new posts, but they cannot publish them to the site. That requires a higher role. This allows users to contribute information to your site, but you still maintain control over what is actually published. As you can see, this is a fl edgling workfl ow for content publishing. In addition to creating draft posts, Contributors can also edit their own posts at any time and delete their own unpublished posts. Contributors cannot upload fi les and images to be used in their own draft posts.Author Role Authors are the next level up the hierarchy. Authors are more trusted individuals than Contributors in that they can upload fi les to be used in their posts and can publish their posts without approval. Likewise, Authors can edit and delete their own published posts. Authors are restricted to working with their own posts. They can read and comment on any post just like any other user, but they can only modify their own content.Editor Role The Editor role introduces two new capabilities. Up until this role in the hierarchy you have been restricted to posts, but the Editor role can also work with pages. In addition, the Editor is privileged enough to modify any content on the site. This role cannot manage users or site settings such as themes and plugins, but the actual content is wide open. In practice, this is the role you assign to the client for a managed WordPress install. It c13.indd 361 12/6/12 1:24 AM 362 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAM provides enough capabilities that the client can manage the day-to-day content of the site, but not so much that he can muck around with the overall site settings and mess things up. Note, however, that Editors cannot manage menus or widget areas, therefore limiting the extent of the content they can manage.Administrator Role This is the root level role. Everything in the WordPress Dashboard is open to an Administrator so you want to assign this role carefully. This role can modify users, themes, plugins, and all of the content. Make sure your Administrator users are security conscious and using good passwords. Should bad guys get access to your Administrator account, they will have full access to your site.Super Admin Role This role is only used on Multisite Networks. Essentially, the primary purpose of this role is to manage the different WordPress sites in the Network and manage the network overall.Role Overview Table 13-1 shows a simplifi ed overview of the capabilities assigned to each role. For more exact information about the capabilities of each role, visit the WordPress Codex at http://codex.word press.org/Roles_and_Capabilities.TABLE 13-1: Capabilities of Each WordPress RoleSUPER CAPABILITY ADMIN ADMINISTRATOR EDITOR AUTHOR CONTRIBUTOR SUBSCRIBERManage network XManage themes X XManage plugins X XManage users X XManage site options X XModerate comments X X X c13.indd 362 12/6/12 1:24 AM Using WordPress Roles ❘ 363Manage categories X X XManage links X X XManage all posts X X XManage all pages X X XManage others’ posts X X XRead and manage private posts X X XRead and manage private pages X X XUpload fi les X X XXPublish posts X X XXDelete own published posts X X XXEdit own posts X X XX XDelete own unpublished posts X X XX XRead X X XX X XExtending Roles In most cases, the default roles will be enough. However, in certain circumstances there may be the need to extend roles to include more permissions or fi ne-grained control over content-editing capabilities.The Role Scoper plugin by Kevin Behrens (http://wordpress.org/extend/plugins/role-scoper/) is a very powerful tool to manage these access control situations. With this plugin, user access is augmented beyond the default permissions covered previously, with specifi c access controls related to content-specifi c settings. c13.indd 363 12/6/12 1:24 AM 364 ❘ CHAPTER 13 STATISTICS, SCALABILITY, SECURITY, AND SPAMThat is, any level of user can have escalated permissions to edit and manage content based on specifi c categories, pages, or posts. This access permission can go both ways to either enable content modifi cation, or the reverse, to remove the ability for a role to read content. For example, you created a multi–product line site. Each product line had a product manager responsible for its content. In this case, each product line became a WordPress category. With this plugin, you were able to restrict product managers to be able to only post new content within their respective categories. Role Scoper is a very powerful plugin that allows you to build fi ne-grained controls. However, it may be more than you need for your particular situation. Many other plugins are available that allow you to supplement the built-in WordPress roles in other ways.SUMMARYThis chapter covered some of the challenges for when your WordPress site begins to get noticed in the web, including managing scalability and performance through caching and load balancing. Popularity also attracts spammers and other ne’er-do-wells, this chapter presented some methods on how to handle spam as well as securing your WordPress installation. Finally, role defi nition is key in controlling workfl ow, and is at the heart of using WordPress as a full-fl edged content management system and in enterprise applications. You will tackle those topics in the next two chapters. c13.indd 364 12/6/12 1:24 AM 14 WordPress as a Content Management SystemWHAT’S IN THIS CHAPTER?➤ Examining content management system tasks that are easily performed with WordPress ➤ Confi guring WordPress to handle more complex content organization and display ➤ Integrating interaction vehicles such as forms, e-mail, and cartsUsing WordPress as a content management system (CMS) seems to come up every month on the web. Run that phrase through a search engine and you will see countless results on the whys, why nots, and hows. It seems that WordPress is trapped with the stigma of being “only” a blogging engine when, as you have discovered by now, it is so much more. Since the fi rst edition of this book, this topic and discussion around it have grown. WordPress is no longer pigeonholed in the “blog engine” space as it once was. This chapter defi nes content management from the perspective of a WordPress system, looks at the major functional areas associated with a CMS, shows you how to implement them via WordPress, and fi nally points out some areas where WordPress, despite its fl exibility and simplicity, is potentially not the best tool for the task.DEFINING CONTENT MANAGEMENT“Content management” has become hard to precisely defi ne because it has been applied to a wide array of software tools and systems. On one end of the spectrum you have wikis, with explicit, multi-author editing and version control, but almost no page organization, navigation, or display mechanics. At the other extreme are commercial software packages aimed at c14.indd 365 12/6/12 1:25 AM 366 ❘ CHAPTER 14 WORDPRESS AS A CONTENT MANAGEMENT SYSTEM the enterprise that handles access control, audit performance, repository functions, and community sharing of corporate documents. Clearly there’s a difference between the “transactional content management” realm of enterprise document control and self-directed publishing, but trying to pin the content management label on just one or the other ignores the richness of the software tools in those spaces. Since the rise of low-cost, easily used Internet tools, content management has more typically been applied to the systems used to build a site for Internet commerce, featuring online catalogs and customer interaction. Where does WordPress fi t on this spectrum? In the narrowest defi nition, blog engines are a form of CMS, handling a minimal number of content types (pages and discussion) in a chronological display order. Although WordPress started out as a blogging system, and some popular opinion still tries to narrowly describe it as such, it has the power, fl exibility, and resources to perform most, if not all, of the tasks required of a package more typically marketed as a CMS. The mechanics of managing a site, administering users, and bucketing content for structure and distribution aren’t specifi c to blogs or any fl avor of content; they require customization, design, and a multi-role delegation system. We, the authors, hope this has been conveyed so far in this book, where we have liberally referred to the “content management” functions of WordPress, and now we can tie the pieces together in a more general CMS view. Following are the CMS features discussed in this chapter: ➤ Workfl ow and delegation — Often the holy grail of the CMS world is enabling multiple authors with minimal technical expertise to control the editing and publishing process. WordPress makes it simple for nontechnical users to add content and manage its distribution. ➤ Content organization — From mimicking a simple network portal to building complex page hierarchies, content organization involves handling multiple, complex types of content and choosing the appropriate display patterns for each. ➤ Interactivity — Mailing lists, forms, discussions, and commerce functions are typical CMS functions that require a bit of WordPress extension. ➤ Other content management systems — As a pure website management system, WordPress can be a powerful editing and content production platform, feeding other content management systems such as Drupal. This chapter also looks at areas in which WordPress is not the best choice.At their core, blogging and content management may have come from different starting points and established their own functional lexicon, but the extensibility, design customization, and diverse developer community around WordPress has blurred the lines between what is “only blogging” and the now in-vogue “enterprise content management.” WordPress in the enterprise is discussed in Chapter 15, but as an introduction to the details of implementing full CMS functionality, here is a list of reasons why WordPress should be considered a fi rst-tier content management system: ➤ Simplicity — From the user interface to content creation, WordPress can be simple or complex to match user skill and deployment requirements. c14.indd 366 12/6/12 1:25 AM Workfl ow and Delegation ❘ 367➤ Flexibility — WordPress handles a multitude of site archetypes, from simple reverse-dated blog entries to crowd-sourced, hyperlocal news sites (check out http://injersey.com) to hierarchies of fi xed and dynamic content showcasing an artist, photographer, or other creative professional, or a vacation destination (check out http://baja.com). ➤ Extensibility — You can fi nd plugins and themes to create a huge variety of visual styles, integrate numerous content types and sources, and simplify the process of going from simple typed content to complex, displayed HTML.The goal in covering WordPress as a CMS is to highlight approaches to solving typical content management problems, building on the techniques and examples provided in previous chapters. Of course, no one wants every conversation to start out with a defense of WordPress, either in these pages or by you in a setting where you are choosing content management tools. Whatever your defi nition of content management, or your goals for creating a website that goes well beyond a list of blog entries, the content management process starts with simplifying the workfl ow.WORKFLOW AND DELEGATIONOne of the primary appeals of a classic CMS is that it simplifi es content creation and management. Closely tied to that effort is a separation of duties, such that those users and administrators with editorial control over the content are given access, responsibility, and control over what is actually published through the CMS.User Roles and Delegation User management in a CMS has all of the separation of powers and policy creation complexity of politics, government, or standards bodies. You have to allocate roles based on the types and cat- egorization of content you expect, as well as set boundaries on users’ abilities to publish and edit previously published content. In a purely multi-author website environment, the distinction may not appear that important, but if you’re using WordPress as the face of an e-commerce site or for a company’s product catalog, multiple departments and approvers typically demand involvement. Kevin Behrens’s Role Scoper plugin was covered in Chapter 13 as part of the security and user management discussion. This plugin allows you to create new roles for your users and assign them very fi ne-grained permissions. In a CMS environment, this would permit you to delegate content generation to different departments and authorize them to make changes only in their respective areas. Assignment of authority goes up the hierarchy of users, not down from an editor to an individual author. In a typical publishing environment, an editor will be able to dole out work to writers and composition experts, creating a workfl ow for the fi nished product that is organized in a tree structure similar to an organizational chart. WordPress mobilizes the leaves in that tree structure: every user that has contributor or author privileges can create content (and upload fi les, in the case of c14.indd 367 12/6/12 1:25 AM 368 ❘ CHAPTER 14 WORDPRESS AS A CONTENT MANAGEMENT SYSTEM authors) and manage publishing of their own posts. Deciding how and where to divide responsibili- ties is a key part of establishing a CMS framework with WordPress:➤ Be diligent about administrator roles. Give them out like root or sudo passwords. At the same time, don’t confuse editors with administrators. Editors may want to change the way a page appears, or aggregate content differently. Administrators are going to fi x themes, core fi les, and plugins, and each has to be clear about the bounds on their domains. ➤ Treat editors as such. They will be given permission to edit pages, modify the content or status of any posts, and change metadata on the WordPress site. They should be using their editorial roles to manage the work of the authors and contributors as well. ➤ If you really want every piece of content reviewed before it hits the public web, separate contributors (who cannot publish) from authors (who can publish their own work but not edit that of others). Establishing a contributor class of users ensures that your editors will be busier, but also fully delegates the publishing decisions to those editors. ➤ Note that roles and delegation cover the creative process, not access control to content once published. As soon as it’s accessible as a published post, it’s public until deleted (and even then, it may be cached or replicated elsewhere through a feed mechanism). In contrast to other content management systems, WordPress does not focus on a mechanism to control access to published content; it’s not about intellectual property management or control in the same way a corporate document repository might track access, references, and provide auditing mechanisms. A wrinkle on the multi-role and multi-user WordPress administration framework is WordPress Multisite, discussed in Chapter 10. WordPress Multisite powers WordPress.com because it allows multiple independent user trees to run independent but cohosted sites. This may be attractive if you have independent product groups or multiple brands that each want their own WordPress installations but you are limited (or want to be restrictive) in terms of administrator people power. Workfl ow Having established users and their roles, the next step is to clearly establish a workfl ow for getting content out of people’s heads and onto the web. After a simple editorial user structure, workfl ow is probably the next most matched term when asking what users associate with mainstream CMS. Two major components to workfl ow within WordPress exist: post revision history and post control. Revision history is visible within the Post portion of the Dashboard, where entering edit mode on a post shows you the list of revisions. If you’re running a system with multiple authors and editors, where the editors may fi ne-tune the fi rst writing output, ensure that the editorial staff is using the revision feature to track content added, subtracted, or different between post revisions. It’s effectively source code control for post content, managed within the MySQL database under WordPress. Although many people are big fans of the simple Dashboard and fi nd it compact yet powerful, some site administrators may fi nd that the interface is too complicated given the technical background of their editor or administrator delegate. Some people freeze up when they have too many options or choices. You can use the WP-CMS Post Control plugin by Jonathan Allbut (http://wp-cms.com/ c14.indd 368 12/6/12 1:25 AM Workfl ow and Delegation ❘ 369 our-wordpress-plugins/wp-cms-post-control-plugin/) to turn off unneeded features. This plugin installs a new control panel that allows you to confi gure the Write Panel to show only the fi elds you want them to see, as shown in Figure 14-1.FIGURE 14-1: Using WP-CMS Post Control to set the Dashboard optionsThere are many options here, but it is a simple management control. Using this plugin is the administrative control step that’s complementary to creating simpler (or more specifi c) post editing panels, described later in this chapter. The second part of content workfl ow is the process of taking posts from the draft state to published state, with stops at “private,” “future,” and “pending” along the way if warranted. A post written by a contributor will be held as “pending” until published by someone with that permission. Much of the post workfl ow happens through the Posts tab on the Dashboard, where the status of each post is clearly labeled, and there are menu items for publishing or making other post status changes such as marking a post as private or setting a future publication time. If you’re running a multi-writer WordPress site, remember that all of the content is stored in the same MySQL database, making it easy for other users to see the current state of the content. WordPress provides the wp_transition_post_status() function for plugins that want to catch individual post status changes, either to update a work-in-progress page or to otherwise signal to other users that a workfl ow change has propagated. c14.indd 369 12/6/12 1:25 AM 370 ❘ CHAPTER 14 WORDPRESS AS A CONTENT MANAGEMENT SYSTEMA particularly interesting plugin to watch is the Edit Flow plugin (http://wordpress.org/extend/ plugins/edit-flow/). This plugin was designed to model a newspaper publishing workfl ow in WordPress. It includes several new post statuses, starting from pitching a story up to the traditional published post. It also includes special story budgeting calendars to make sure you have content spread out appropriately and assigned to writers and photographers for proper content completion. Additionally, this plugin includes behind-the-scenes notes between the editor of the site and the author to help with the publishing workfl ow with remote workers. It is defi nitely a niche plugin, but if your needs align, check it out.CONTENT ORGANIZATIONThere is an ongoing discussion, bordering on a fl ame war, about posts in a WordPress site that is being used as a traditional, static content website. Posts are an indelible part of WordPress and absolutely have a place and use in any website, but the common argument is that posts are natu- rally chronological and that only time-based content fi ts this paradigm. Posts can represent any small content block that can be used multiple ways, and part of using WordPress as a CMS involves changing your strategic thinking about what types of content are used to what effect on the site. Here are three simple examples of using posts for a commerce site: 1. Create a post for each product that you sell. Comments on the post allow users to offer feedback and recommendations. 2. Create a category or tag for each product on the site, and then organize posts about the product. The fi rst post in each category should be the product information, and possibly a link to a shopping cart via which to purchase the product — something covered shortly. Now you can use the posts structure to provide deeper information about each product: Why are you offering it? How is it created, defi ned, or sourced? What other reviews, feedback, or public commentary exist? 3. When creating a help section for a product, each help topic could be a post. Each help topic would be one small bite-sized piece of content that addresses a specifi c task or feature, using the tag and category mechanisms to sort and provide navigational guidance to users looking for self-directed help. Comments on the posts allow for users to describe the relative helpful- ness of each post. Similarly, although not e-commerce, the jQuery team is using this method to document its API at http://api.jquery.com, creating a help resource and community resource via comments, all in one.In every one of these simple examples, you want to change the default behavior of WordPress away from showing the most recent posts, and instead create a mix of static and dynamic homepage content reminiscent of a static website. You can see a variety of WordPress CMS application examples at http://wordpress.org/showcase/tag/cms.Theme and Widget Support Theme support for content management is key. Your goal may not be to make WordPress look decidedly non-blog-like but, rather, to fi nd a theme that gives you the fl exibility to display the c14.indd 370 12/6/12 1:25 AM Content Organization ❘ 371 types of content in the visual style that fi ts, whether it’s a product sales site or an online newsletter. This is a great use case for the Thematic (http://wordpress.org/extend/themes/thematic) framework with its 13 widget areas and powerful child theme extensibility. As an extreme case, the P2 theme (http://p2theme.com) developed by Automattic puts a posting panel, real-time updates, and inline editing right on the homepage, combining the best of Twitter, a blog, a discussion forum, and a news site. WordPress can be molded through themes to look completely different from any other WordPress site. If you’re going to be using a theme with widget areas and want to expand the content types available in those sidebar areas, you’ll want to leverage the TinyMCE JavaScript-based editor to turn HTML text areas into something more theme-appropriate. The Rich Text Widgets plugin addresses the challenge that default text widgets support only plain old text. When you enable the Rich Text Widget plugin by Julien Appert (http://wordpress.org/extend/plugins/rich-text-widget/), as shown in Figure 14-2, you have a new widget available in your widget control panel. This widget has the built-in TinyMCE editor, so your content creators can put more than text in the sidebar.FIGURE 14-2: Editing a rich text widgetYou do have to exercise some caution when using this plugin. Usually, your sidebar and other widget-ready areas have fi xed widths. With this plugin, your content creator can upload anything into the widget and potentially break the layout of the site. However, this can be remedied with some proper training. c14.indd 371 12/6/12 1:25 AM 372 ❘ CHAPTER 14 WORDPRESS AS A CONTENT MANAGEMENT SYSTEMThe bundled TinyMCE editor is workable but doesn’t support some frequently used features such as adding tables. The TinyMCE Advanced plugin by Andrew Ozz (http://wordpress.org/extend/ plugins/tinymce-advanced/) steps in and tries to address these shortcomings; however, be forewarned that the more elaborate your content, the more opportunity you create to break your site (again) with ill-formatted or rendered tables. Figure 14-3 shows a couple of features turned on, but there are many more.FIGURE 14-3: Using TinyMCE Advanced to edit a postHomepages Remember high-school writing courses in which every story had to have a narrative hook? The hook was the point in the story where you established what made your story unique or interesting, and encouraged your reader to keep going. A good narrative hook on a WordPress site will engage the reader and kick off the remainder of your story line, whether it’s product-related content, or a mix of static and time-sensitive posts. The common approach is to set a static front page. As discussed in Chapter 9, you can do this in several different ways. The easiest is to use the WordPress Reading Settings Dashboard to set a static page for your front, or homepage. In addition, this page could use a page template to modify and distinguish the layout from the rest of your site. You’ll need to create a page (not a post) specifi cally for this purpose, and then use the Dashboard to set it as the front page. c14.indd 372 12/6/12 1:25 AM Content Organization ❘ 373The other option is to use a special WordPress template fi le to serve as your front page, replacing the default listing of posts. WordPress looks for a template fi le named front-page.php in your theme, as discussed in Chapter 9. Using a template fi le will afford you more fl exibility in the layout and functionality of your index page because you can edit the PHP code directly, choosing, for example, to list sticky posts or featured products fi rst, and then related content or more recent chronological posts. Using a mix of additional page data fi elds and the custom loop query mechanisms described in Chapter 5, you can hand-tune the selection of content for your homepage as fi nely as you want.Featured Content Pages A good tool for your narrative hook on your static index page is a featured item. This is very common among the magazine-style themes in particular as well as many other websites. Often, in the top third of the content area, you will see a large image area with a headline featuring content from elsewhere in the site. This position is sometimes called the “hero spot” and is featured prominently on popular websites. It is a frequently deployed device because it works. Generally when you deploy a featured item on the index page, you like to have several different images and use jQuery (or another JavaScript library) to cycle through them. That way, you are not relying on one hero item to save the day, but putting forth a couple of different ideas, and with luck, one will catch the visitor’s eye. The goal here is to feature items managed as posts, custom post types, or media by WordPress so that the editorial staff can control them rather than the site administrator. The fi rst thing to do is set up a system for the featured items. You can use a category named “Features” and use just those posts for the slideshow. But that means that in other parts of the site, if there is a news section that shows all posts, you will want to exclude this category from those Loops, which can be a pain. This is how you used to manage this type of feature on a WordPress site, and some themes continue to do so. However, as covered in Chapters 7 and 9, you can use custom post types to achieve this functionality without the extra loop overhead. Again, this is only one way to implement this content management element; there are many others. In this example, you are going to edit the theme template fi les directly, but this functionality could be built into a plugin also. The plan is to showcase three random features from the “slides” custom post type for display. First, register a new custom post type, as discussed in Chapter 7. This code goes in your functions.php fi le. For this example, it might be something like this:/* * SLIDES FOR FEATURE * Register post type for feature */ add_action( 'init', 'wppro_create_post_types' ); function wppro_create_post_types() { register_post_type( 'slides', c14.indd 373 12/6/12 1:25 AM 374 ❘ CHAPTER 14 WORDPRESS AS A CONTENT MANAGEMENT SYSTEM array( 'labels' => array( 'name' => _x( 'Slides', 'post type general name' ), 'singular_name' => _x( 'Slide', 'post type singular name' ), 'add_new' => _x( 'Add New', 'Slide' ), 'add_new_item' => __( 'Add New Slide' ), 'edit_item' => __( 'Edit Slide' ), 'new_item' => __( 'New Slide' ), 'view_item' => __( 'View Slide' ), 'search_items' => __( 'Search Slides' ), 'not_found' => __( 'No Slides found' ), 'not_found_in_trash' => __( 'No Slides found in Trash' ), 'parent_item_colon' => '' ), 'public' => true, 'exclude_from_search' => true, 'supports' => array('title','thumbnail','editor'), ) ); }For the display on your site, you are either going to edit your front-page.php template fi le or make a new page template fi le for your index page. These code changes will go into that fi le. Next, you have to get the slides from the database. You can get these posts with a simple WordPress get_posts() function: global $post; $args = array( 'post_type' =>'slides', 'numberposts' => 3 'orderby' => 'ASC' ); $slider_posts = get_posts($args);You can tell from the parameters what this function will return: three custom post types of the type slides, in ascending order. You can change numberposts to be –1 to get all of the posts. Then, in the content area of the template fi le, you mix a little HTML for the jQuery to hook into and then loop over the result object:<div id="slideshow_container"> <div id="slideshow"> <?php if($slider_posts) { foreach($slider_posts as $post) : setup_postdata($post); // get image $thumbnail = wp_get_attachment_image_src(get_post_thumbnail_id(), 'home-slide'); if ($thumbnail[1] == "600" && $thumbnail[2] == "160") { //also check thumbnail dimensions in css ?> <div id="feature-<?php echo $post->ID; ?>" class="slide"> <a href="<?php the_permalink(); ?>" title="<?php the_title(); ?>"> c14.indd 374 12/6/12 1:25 AM Content Organization ❘ 375" title="<?php the_title(); ?>" /> </a> </div> <?php } ?> <?php endforeach; ?> <?php wp_reset_postdata(); } ?> </div> </div>What you are doing here is creating some wrapping divs to contain the slideshow, looping over each custom post type in the query result, and pulling out the featured image. When you put this to use, the featured image is specifi cally sized, which you are checking so that the slide does not break your theme layout. Finally, each image is wrapped in an anchor tag linking to the post content you authored in the Admin Dashboard. This can be extremely convenient because you now have featured slides advertising on your index page that link to individual landing pages, which makes it handy for tracking success rates through your traffi c analysis. Furthermore, you are not cluttering up your traditional post and page content with ephemeral advertising posts. If you view your site now, you will see three stacked images on top of each other, so the next step is to take these posts and use a little JavaScript magic to turn them into a slideshow or carousel. Many people are big fans of the jQuery Cycle plugin by Mike Alsup (http://malsup .com/jquery/cycle/). Note that this is a plugin for jQuery, and not WordPress. This plugin is really easy to use and has several neat transition options. Using this plugin, you can convert the HTML into an autoscrolling slideshow. This JavaScript code goes into the bottom of your page template fi le or where you would normally place your JavaScript. The jQuery could be something like this:$('#slideshow').cycle({ fx: 'scrollHorz', speed: 500, //time the transition lasts timeout: 10000, //time between transitions pause: 1, //stop the show on mouseover random: 0, //random order (not using a random order) delay: -1000, //delay before show starts first transition next: '#next', prev: '#previous', pager: "#slidenav", pagerEvent:'mouseover', // name of event which drives the pager navigation autostop: true, // true to end slideshow after X transitions //(where X == slide count, use this to help with out of control javascript on // some browsers) autostopCount: 100, // number of transitions (optionally used with autostop to define X) // callback fn that creates a thumbnail to use as pager anchor c14.indd 375 12/6/12 1:25 AM 376 ❘ CHAPTER 14 WORDPRESS AS A CONTENT MANAGEMENT SYSTEM pagerAnchorBuilder: function(idx, slide) { slide.id = "slide"+idx; var desc = jQuery('#'+slide.id+' img:first').attr("title"); return '<a href="#" title="'+desc+'">'+(1+idx)+'</a>'; } });Experiment with the different effects and timing using the other parameters you can set to create unique results. This same method could be used to showcase some testimonials. Either keep it in a slideshow pattern, as outlined previously, or pull a random post from the testimonial category. Rather than using images as your content, you can have the actual formatted post data. You are only limited by your imagination.Content Hierarchy In addition to the featured item concept to draw users’ attention, most content management systems will allow you to create a content hierarchy to improve navigation once you’ve hooked the user. A typical hierarchy contains content of different types in a tree-like structure to impose navigational patterns, and that allows you to mix static content features with more dynamic content. One obvious path to a content hierarchy is to use categories and tags to sort posts into related groups. This is useful when you are using posts as the primary content type and organize equivalent classes of posts by category or unique tag information. In addition, you saw in the previous section of this chapter how posts can be used for featured image content on an index page carousel. The custom taxonomy features discussed in Chapter 7 provide another way to organize and search posts, giving you even more fl exibility when customizing a theme’s Loop. This section digs into these custom pages and post hierarchies more, providing examples of plugins that let you craft the content management aspects of WordPress to suit your desired site look and feel. You can start with a complex navigation challenge: you have a hybrid site that has sections where pages are the obvious content type, but you also have some sections where post categories make more sense. You do not want to manage a hard-coded navigation tree, and implementing menus isn’t perfect because the post content is (intentionally) regularly changing.One solution is the Page Links To plugin by Mark Jaquith (http://txfx.net/wordpress- plugins/page-links-to/). This plugin creates a new fi eld on the page Write Panel. Using this fi eld, you can create a page that functions as a redirect to another web page. This enables you to use the menu system as your site’s global navigation, but still empowers you to create menu items that can redirect to offsite links. Or, more often, you can now create a menu item as a page but have it redirect to a post Loop page. For example, pretend that under your About Us menu, you have the traditional History (of your company) and Contact Us pages, but you also have a job posting page. But your company uses a third-party service for job postings, which creates a problem in your navigation. With this plugin, you can create a new page called Careers, but have the page link to the third-party job-posting site instead. You can see how this would be set up in Figure 14-4. c14.indd 376 12/6/12 1:25 AM Content Organization ❘ 377FIGURE 14-4: Creating a page that links to third party with the page links to plug inThe next challenge with a large site is managing the pages. After a while, your site grows to have multiple pages, under multiple parent pages. This structure is necessary to make your site coherent, as discussed in Chapter 9. Themes have several ways to handle global navigation, and determining which method your theme uses is important. Most themes are moving toward using the WordPress menu system. The menu system is nice and fl exible, but it is disconnected from your actual content. With the menu system, you can automatically add pages to the navigation, but only at the top level. But when you remove a content page in the Dashboard, it does not affect the menu, leaving you with orphaned navigation links. This disconnect can be very baffl ing to inexperienced WordPress administrators, and can be FIGURE 14-5: The Parent frustrating for experienced administrators that the two systems are pages drop-down selection on not coupled. a site with just a few pages A second, older method uses the built-in Parent pages functionality. Page management is serviceable but can get confusing quickly when you have many pages. And when you need to move pages around, using this method can get quite tedious, as you can see in Figure 14-5. One way to get the simple menu management built into WordPress with the connected content-to-navigation-item association is with the Page re-Mash plugin, originally by Joel Starnes c14.indd 377 12/6/12 1:25 AM 378 ❘ CHAPTER 14 WORDPRESS AS A CONTENT MANAGEMENT SYSTEM and updated by Matt McInvale. To get Page re-Mash to work on a current version of WordPress, download the original PageMash plugin from http://wordpress.org/extend/plugins/ pagemash/ and then replace the pagemash.php fi le with the updated one from http://binarym .com/2010/pagemash-trash-auto-draft-and-wordpress-3-0/. Page re-Mash, in all its AJAXy goodness, allows you to move pages around in a drag-and-drop natural fashion. As you can see in Figure 14-6, pages can be nested and organized in a very intuitive interface. Page re-Mash requires your theme to use the wp_list_pages() function for your site navigation and not the built-in WordPress Menu System. The plugin will let you hide pages from the wp_list_pages() function, offering even more control over the whole navigation structure of your site.FIGURE 14-6: Managing page order and nesting with the PageMash pluginAssuming you are following the “posts are generic content” lead and are using posts for various types of content in your site, the Yet Another Related Post plugin by Michael Yoshitaka Erlewine (http://wordpress.org/extend/plugins/yet-another-related-posts-plugin/) is a nice add-on. This plugin provides a list of additional content that is possibly related to the current entry. Using this type of functionality will encourage visitors to explore other areas of your site that are of similar interest. Like the jQuery API documentation center mentioned previously, this plugin would provide additional help topics related to the current issue. In short, using this plugin creates cross- references in your website among related content. c14.indd 378 12/6/12 1:25 AM Interactivity Features ❘ 379The Pods Framework plugin (http://wordpress.org/extend/plugins/pods/) takes structuring data even further. Pods allows you to create new content types above and beyond posts, pages, and custom fi elds. You can then normalize these new types with relationships among the data. You can use these new content types and relationships in your Pods pages that support special Pods syntax and PHP code. Pods is a much more complex system but it also is much more powerful.INTERACTIVITY FEATURESThe most basic interactivity feature is Search, discussed in Chapter 12. The other primary user interaction features associated with a CMS are forums, forms, and basic e-commerce features.Forums Comments on posts are the simplest content discussion type. At times, you’re going to want to move from content that you create in an attempt to stimulate conversation into user-led and threaded conversation. A forum is an open discussion, most commonly called a bulletin board in the pre- broadband days of the Internet. The easiest way to add forums to WordPress is through bbPress (http://bbpress.org), a WordPress-related project also delivered by Automattic. bbPress will share user data with WordPress so registered users can participate in forum discussions. It’s possible to load them both and have your forums simply appear as a section of your website. If you want a simple forum feature as a content type, the plugin route is likely to produce an acceptable result. On the other hand, if you want to integrate multiple content management repositories into a single user experience, take a page (literally) from WordPress.org: bbPress powers the WordPress.org user-generated support area.Forms The next challenge for a website is creating and managing forms, such as contact forms and other similar web form–to e-mail functionality. Countless plugins are available for contact forms, but for a full-featured site, you will eventually have to move beyond this. For the longest time, the cForms 11 plugin by Oliver Seidel (http://www.deliciousdays.com/cforms-plugin) has been the regular stand-in. CForms works very well and is extremely powerful. You can customize it to all ends of the earth, but the user interface is very daunting at fi rst. You cannot really hand off CForms to your content administrator to make new forms as needed.An alternative to CForms is Gravity Forms by RocketGenius (http://www.gravityforms.com/). This is one of the few plugins mentioned in this book that costs money to use. But to be honest here, Gravity Forms is a very enticing prospect. Ask any WordPress developer what her favorite plugin is, and if she has used Gravity Forms, that’s usually the answer. Gravity Forms lets you create any type of form you need with a simple, easy-to-use AJAXy interface. It is so easy to use that many content administrators are shown how to use it. Not to gush too much, but the clean, intuitive interface is truly one of the best among plugins. In addition to the user interface side, the HTML rendering is top notch. It looks fantastic without any additional styling required. However, should you desire to change the look and feel, the HTML c14.indd 379 12/6/12 1:25 AM 380 ❘ CHAPTER 14 WORDPRESS AS A CONTENT MANAGEMENT SYSTEM is fi lled with CSS class and ID hooks for you to use. In addition, this plugin is so popular that many themes include styling for it. A fi nal, powerful feature of Gravity Forms is that, in addition to the traditional “e-mail the form contents to a specifi ed address” functionality, Gravity Forms also adds a Dashboard module that tracks the forms submitted. Although CForms has similar functionality, the usability of Gravity Forms really justifi es the cost.E-Commerce If you are building a site with featured products and pages, product tags, and categories, ideally you’d like to sell something. Shopping cart and payment systems integration fi ll the last category of user interaction. If you search the plugin directory on WordPress.org, you will see at least a dozen different shopping cart and checkout plugins available. Rather than itemize them all, here’s a quick checklist of things to look for: ➤ How hard is it to confi gure the shopping cart? Are you going to be burdening your administrators with minor details such as updated discounts, or can content managers handle that task? ➤ What kinds of statistics can you get from the cart? Learning how and why users abandon items will help you improve the site, whether through more product information or an easier checkout process. ➤ What payment systems are supported? If you’re not looking for anything more complicated than the ability to accept PayPal payments with a specifi c product or item number fi lled in, you can use PayPal button templates and hand-edit them into your pages or sidebars.The WP e-Commerce plugin (http://getshopped.org) combines nearly all of the extension mechanisms covered: it uses custom post types for product pages, organizes them in custom taxonomies, and adds plugin-specifi c database tables to maintain product attributes. It integrates with a variety of payment mechanisms and clearly demonstrates that you can give WordPress a hand-crafted look and feel.OTHER CONTENT MANAGEMENT SYSTEMSYou have seen how WordPress is so much more than a blogging platform. It can be used for a wide range of different types of websites, but aside from what a plugin can offer — which can be substantial — the functionality of the WordPress Core is what it is. Sometimes you want to complement your website with additional functionality found in other traditional web-based applications, such as forums like bbPress, social network features like BuddyPress, e-commerce applications, or other CMS solutions. Given the range of content management systems available, and the fact that most enterprises already have one, if not several, content repositories up and running, it’s often useful to integrate WordPress with another CMS. This section takes a brief look at when you should use WordPress as an external content consumer or producer and when you should not use WordPress as the core of a content management system solution. c14.indd 380 12/6/12 1:25 AM Other Content Management Systems ❘ 381WordPress Integration Integrating an application like WordPress with another content-oriented application requires that you align user management, content packaging and, potentially, look-and-feel issues. It’s not something easily accomplished with a plugin or theme extension, and typically requires custom bridge code. You will fi nd building blocks in the plugin directory; this section presents a rough outline of the problems to be solved. How does the external system provide content? Are you getting an RSS feed, in which case you can use the RSS aggregator discussed in Chapter 11 as a starting point, or do you get raw JSON that requires editing and parsing before being turned into a post?If you have a remote resource URL, can you embed it using an oEmbed (http://oembed.com) provider plugin? oEmbed takes a URL and returns a variety of content types that can be integrated into WordPress themes, allowing them to be displayed without WordPress having to parse the content type. Chapter 11 also touched on some of the oEmbed features of WordPress. Do you need to manage user credentials between the sites? Do you have to store user login information for the external site (in the WordPress MySQL database, using a table created by your plugin), and if so, how do you handle error conditions such as password changes or user deletion in the remote system? It’s possible to treat WordPress as a blog-only engine, producing blog posts for consumption by a CMS like Drupal. In this case, WordPress becomes a component of Drupal, managing its content as the source of the blog posts type but ceding presentation control to the Drupal confi guration.Where Not to Use WordPress Not every content management problem is a nail waiting to be pounded home by the WordPress hammer. Sometimes you’ll need to pick a different tool, or set of tools, for the job: ➤ Handling rich media — Streaming video, audio, and images with copious quantities of metadata can be displayed and included in WordPress posts, but if you want to be able to tag and index video fi les or search images based on their EXIF (Exchangeable Image File Format) tags, you probably want to use a CMS designed for rich media management. ➤ Backend for Rich Internet Applications — The next generation of mobile clients is emerging. They usually expect to talk to a backend data repository or service, rather than a full-featured website. WordPress eventually emits HTML, not JSON or other data packaging formats most likely consumed by APIs. WordPress can do it, but is it the right tool? ➤ Simple network storefront — If you’re just building a store, use a storefront builder with shopping cart, payment systems, and product catalog. You’ll miss the integration of product discussion, feedback, recommendations, and the ability to describe how and why you’re carrying (or have built) a particular product, all of which are possible using the approaches described in this chapter, but sometimes you just need users to be able to click and buy. ➤ Event and calendar focus — Several types of sites manage calendars, event registrations, event materials, and notifi cations or reminders about upcoming calendared items. c14.indd 381 12/6/12 1:25 AM 382 ❘ CHAPTER 14 WORDPRESS AS A CONTENT MANAGEMENT SYSTEMWordPress does not (yet) have a built-in highly functional calendar and event management plugins, making this an area where using Drupal or BuddyPress may be simpler out of the box. BuddyPress in particular has a fair number of features for calendar-driven activities and content, but gives you the context of a community management tool, similar to a private social network, rather than a pure content management system. ➤ Force-fi tting a solution — If you have to make modifi cations or changes to the WordPress Core, either you are doing something wrong or, more likely, WordPress is not the right solution. When hacking the core WordPress code, you break your upgrade path, such that you overwrite any changes you made to the core package fi les that enabled your specifi c functionality to work as soon as a new version of WordPress was released. As stated in Chapter 4, don’t hack the core. ➤ Plugin overload — Plugins rock, and a large portion of this book has been devoted to identifying appropriate plugins for specifi c functions or outlining how to create your own for those uses. But you can go overboard. If you are using too many plugins, you may hurt the performance of your site and probably make it more fragile as a result of unknown dependencies between the plugins. Each plugin also increases the resource requirements of your site, specifi cally, memory and processing power.SUMMARYWordPress is a powerful content management system with many of the features found in commercial systems that pre-date the blogging craze of the early 2000s. In equal parts tribute to its open source roots, strong developer community, and simple extensible design, WordPress has established itself as a tool that goes far beyond a simple blog engine. Chapter 15 looks at enterprise-scale WordPress deployment. c14.indd 382 12/6/12 1:25 AM 15 WordPress in the EnterpriseWHAT’S IN THIS CHAPTER?➤ Determining if and how WordPress could benefi t your company ➤ Understanding ways to tune your application stack to help WordPress scale to meet traffi c demands ➤ Evaluating diff erent corporate authentication integration options What exactly is enterprise software? Is it more than a marketing term, one that is used to nebulously declare that my software is better than yours? Just like using WordPress for a CMS, we (the authors) think this topic needs to be put to rest. Obviously, developers are using WordPress as a CMS; you just read a whole chapter about it. Likewise, companies, or enterprises, are using WordPress every day. Just take a look at http://en.wordpress.com/ notable-users/ and you see many big names, ranging from news sites, to technology sites, to Fortune 500 companies using WordPress as part of their enterprise solution. This chapter looks at the motivations for using WordPress in your small or large enterprise. You will also look at the reasons WordPress may not be a good fi t. If you decide to take the plunge and try WordPress for your enterprise, you will cover some methods for making it scalable and techniques for integrating authentication and content into a corporate environment. These techniques will also work on a stand-alone site, so even if you are not using WordPress in a corporate environment, many of these approaches will still apply to your site.IS WORDPRESS RIGHT FOR YOUR ENTERPRISE?Again, what exactly is enterprise software? In the most general terms, enterprise software solves a company-wide requirement or need rather than focusing on the necessities of a certain team or department. Often, enterprise software will integrate with other software pieces or business processes, such as a corporate authentication system or a standard for web servers. c15.indd 383 12/6/12 1:26 AM 384 ❘ CHAPTER 15 WORDPRESS IN THE ENTERPRISEBut frankly, what makes a software package enterprise-worthy depends on your actual enterprise requirements. Clearly, WordPress works for certain businesses, and will most likely work for yours. Following are some reasons why. Many of these reasons are plain old reasons to use WordPress, or reasons to use WordPress as a CMS, which are essentially one and the same. Look at all the functionality you receive out of the box when you use WordPress. WordPress, by its very nature, is easy to set up and use, and is search engine–optimized, security-aware, and well maintained, and countless other features have made it as popular as it is today. For our enterprise, this base functionality is what allows us to create fully functional, professional websites quickly, whether they are for one of our marketing initiatives, a new brand, or for a department or a client. This standardization, coupled with theme development consistency covered previously, ensures that our website infrastructure is predictable and manageable, thus making the development process more effi cient and cost effective, all of which are enterprise-worthy goals. WordPress works in the enterprise environment for other reasons, as covered in the previous chapter about using WordPress as a content management system. The primary benefi t is the capability to delegate content creation to department owners. There is no way the development team can know the happenings and updates of every department company wide. Furthermore, even if these other departments provided content and relied on the web developers to perform the updates to the sites, the developers could be endlessly occupied with maintenance work. By using WordPress and some select plugins you are able to hand the updates back to the respective departments to manage their own content creation, control, editing, and maintenance cycles. WordPress is extensible. This has been covered throughout this entire book. You can extend WordPress in countless different ways by using plugins, and if the plugin that you need does not exist, you can use the plugin API to make your own. This allows you to integrate WordPress into your existing IT infrastructure. The simplest form of integration is using RSS (really simple syndication), which does not require a plugin. We use RSS throughout our company as a way to organize content coming from different locations and reuse that content in new places. For example, press releases are syndicated from one central site, and by using tags and post categories, these content pieces are broadcast to the individual department sites as needed. This permits our content creators to post once and publish across a wide array of websites. Furthermore, using RSS you are able to publish alerts and other timely news pieces from a central site to various locations around the country for use in their intranets and portals. This provides you with a one-stop location to publish from, and presents the consumers with a one-stop location from which to review the information. Other integration pieces could include authorization with an existing identity provider, which is covered later in this chapter, calendaring applications, project management, or system status indicators. Because of the open API, you could integrate anything that you put your time and talents to. Another reason is cost — you cannot beat the price of WordPress. For the actual outlay of money your company would have to pay to try WordPress in your enterprise, you can afford to give it a try and see if it solves some business needs (assuming, of course that you follow good security practices). c15.indd 384 12/6/12 1:26 AM When WordPress Isn’t Right for You ❘ 385WordPress is open source software. That means that when you download it, you have everything. There are no magic compiled libraries of which you cannot see the direct functionality. Being open source and completely transparent prevents vendor lock in. Should you decide in the future that WordPress is not the right fi t, all of your content is extractable. Sure, Automattic is the brains behind WordPress, but with access to all the source code you can always maintain the code should Automattic go away. Or you could fork the codebase and make your own changes if you do not like the direction Automattic is taking, although other risks are involved here, such as disenfran- chising the WordPress community by not respecting the spirit of the licensing, or in other words, changes and improvements should be contributed to the greater community. Generally, a better approach would be to get involved with the development and direction of WordPress, which is covered in Chapter 16.WHEN WORDPRESS ISN’T RIGHT FOR YOUDepending on your circumstances, WordPress can be a good fi t for your company’s needs. But also consider the fl ip side. There are times when it does not match up with your company’s goals, virtues, or culture, or the functionality does not match up with your needs or requirements. Here are some examples of when WordPress may not be the right fi t. WordPress may not have the exact functionality your company requires. It is not a panacea and cannot be all things to all people. For example, editorial workfl ows and default permissions are two places that may not line up directly. Plugins exist or are being developed that address these defi ciencies, such as CoPress.org’s Edit Flow plugin (http://copress.org) and the Role Scoper plugin covered previously. Should you fi nd a requirement that a plugin does not address, perhaps you have actually stumbled across an opportunity to develop one yourself. This next challenge is not WordPress-specifi c, but a common enterprise concern about free/open source software (FOSS) is that there is no one entity to hold accountable. Sadly, this is a reality for some companies. They want someone to hold accountable should something go wrong. In the worst circumstances, this could be you. At the same time, misconceptions about licensing, copyright, copyleft, and layering of software still persist in the business and technology communities. Some of these were touched on in Chapter 1. Likewise, there is no “go to” for support situations. But if you look around, you can fi nd copious amounts of information on the Internet, both good and bad, and there are tons of consultants (possibly including you, after reading this book). Automattic also offers paid support through its WordPress VIP Program (http://vip.wordpress.com/our- services/#self-hosted) for companies that truly want to pay for accountability. Because it is open source software, anyone and everyone can develop for it. When picking plugins, you are at the mercy of the developer. Short of doing it yourself, you do not know the quality of the plugin or the developer’s credentials and security awareness. So prepare to get your hands dirty and actually evaluate the code you are going to use on your site. Be sure you know what you are getting into with a plugin. The last challenge is the development progression, which begins with local development, then moves to a staging or quality assurance server, and then fi nally deploys to a live production server. In most cases, this progression is not a big deal. Themes and plugins developed locally can easily be deployed through these stages. The challenge really comes into play when you are making drastic content c15.indd 385 12/6/12 1:26 AM 386 ❘ CHAPTER 15 WORDPRESS IN THE ENTERPRISE changes on a production site, such as massive copy revisions to a set of product line pages. Aside from multiple imports and exports of the data or database syncing, a viable, low-maintenance solution for this challenge is still needed. As touched on in Chapter 3, however, there are smart people working on this, such as Crowd Favorite’s RAMP.SCALABILITYAt some point, the question arises — can WordPress scale? And the answer is, of course it can. Just look at WordPress.com statistics (http://en.wordpress.com/stats/traffic/). You can clearly see that it is capable. But the actual task of scaling a WordPress installation involves many layers, including the WordPress code, plugins and themes, the PHP version and settings, the web server software and the underlying operating system, and fi nally, the actual server hardware. The key to scaling a WordPress installation is to secure and tune each of these layers.Performance Tuning Securing and tuning your WordPress installation was covered back in Chapter 13. Be sure to review that content. You’re going to touch on more enterprise-specifi c issues here, with the assumption that in a corporate technology deployment, you’ll have access to the web, database, and fi le servers that comprise the bulk of your WordPress installation. We are big believers in DevOps, and you, as the developer, should have knowledge and access to all these layers to understand how all the moving parts work together. Sadly, in some organizations these levels remain in department silos. Tuning your theme should be part of any theme development process. That process includes checking the fi le sizes of all images, making sure the JavaScript and CSS are as small as possible, perhaps even minifi ed, and reducing the total number of HTTP requests a browser has to make. Using a tool such as YSlow! for the Firebug Firefox add-on or Chrome developer tools (http://developer .yahoo.com/yslow/) can help isolate these problems. Our caution about YSlow! is that although it is a nice tool to assess slowdowns, it was designed by Yahoo! for Yahoo!, and even though this is talking about scalability, Yahoo!’s sense of scale is likely bigger than yours. So, take the results with a grain of salt and use some commonsense in weeding out the low-hanging fruit. Generally, good web development practices will help your theme scale. For plugins, you have to look at the code. As mentioned previously, it is unlikely that you know the credentials or skill level of the plugin developer or the terms under which it was created. Some plugins are created in a straightforward, get-it-done style and may not be very effi cient, even if they are effective. You can often see this style with multiple SQL queries to get the information required at any given time rather than a thought-out data access plan. If you are making improvements to existing code, notify the creator. Put your enhancements back into circulation so the entire community can prosper. Chapter 16 offers additional information on supporting the WordPress community. Scalability really goes hand in hand with performance. The more effi cient your website is, the easier it is to handle more requests and therefore scale. For the PHP layer of the application stack, turn off any PHP functionality you are not using. This is good for performance, security, and scaling. Much c15.indd 386 12/6/12 1:26 AM Scalability ❘ 387 of this was covered in Chapter 13 under the subject of security and performance; here, the same rules apply for scalability.In your php.ini fi le, disable any extensions you are not using, like all those extra database extensions. The default php.ini fi le is designed to work for most people in general circumstances. In other words, it is designed to just work for everyone. Here, you are talking about tuning it to meet your specifi c needs and requirements. The following are pretty safe settings to turn off:;Hide PHP for security expose_php = Off ;Turn off for performance register_globals = Off register_long_arrays = Off register_argc_argv = Off magic_quotes_gpc = Off magic_quotes_runtime = Off magic_quotes_sybase = OffSet your memory allowances to the correct values for your server environment and needs. Make sure error reporting is confi gured properly for the environment — do not show errors on the production site. The next layer up is the web server software. Apache is the most common, but WordPress can run on any number of web server applications. In general, do some research on your web server and the functionality it requires in order to tune its operation. Turn off any module or extra features you are not using. Like PHP, the stock Apache confi guration fi le is designed to work for most people in a general case. It is in their best interest to reduce the amount of effort to get something to work from the get-go. This can be a huge barrier to entry if too much tweaking is needed just to get something to work. Tuning for scalability is the exact opposite of this general use case scenario. You want to disable as much as possible to make the software as lean as can be and still serve your sites properly with only the functionality your sites require. A side effect of slimming down your confi gurations is that you also increase your security posture by not having as many options to exploit. Another option for scaling is to consider serving static content from an assets server or Content Delivery Network (CDN). This is a specifi c case of throwing more hardware at the problem, which is looked at shortly. In short, using one web server for serving dynamic content and another for serving the static assets, such as images and CSS, can reduce the load across the board. Different web servers have different strengths. Moving your static content to a secondary URL on a web server using lighttpd or nginx, which are better at serving this type of content, may be more effi cient because each web server can be tuned for a more specifi c function. This will also reduce the load on your dynamic content server, giving it more resources to perform its own duties. A faux method is also available here to accomplish similar results. You can serve static assets from a subdomain, even if it is on the same server. Most web browsers are set to download two to four items in parallel at a time. By moving some of these requests to a subdomain, such as static.example.com, you can trick the browser into effectively doubling the number of items being fetched at a time. c15.indd 387 12/6/12 1:26 AM 388 ❘ CHAPTER 15 WORDPRESS IN THE ENTERPRISEMoving your static assets to a CDN accomplishes the same thing, but on a much larger scale. CDNs distribute your content across their network of servers, so this not only off-loads the transfer from your web server, but it can also make the content geographically closer to your visitor. However, you are also now relying on a third party for portions of your site.Caching Caching can occur at the database level, too. Previously, you looked at different levels of caching, ranging from in-memory cache using Memcache, to the WordPress transient cache of frequently accessed information, and the WordPress plugin Super Cache, which can bypass the entire dynamic nature of WordPress altogether and create static HTML fi les. The database level also has several opportunities for optimizations. MySQL has two main storage types for tables: MyISAM and InnoDB. Others are available, but these are the two that MySQL installations have enabled by default. The ISAM table type was the original storage engine for MySQL. The MySQL team later improved the engine and created MyISAM. MyISAM is a good general-purpose storage engine. It performs better with a table with many reads or many writes, but not both. That is, it is a good for storing or retrieving data, but not ideal for a situation that requires frequent switching between the two. This is also the default table type for WordPress. InnoDB, on the other hand, provides better concurrency, through row locking and transactional support. InnoDB can use non-locking reads to maximize effi ciency and performance. This makes InnoDB a good storage engine for large volumes of data and datasets that are used in both read and write contexts. If you’re going to use WordPress in an enterprise where you have many contributing users, or lively discussion of topics posted by a core group, the write and update load on the database will be signifi cantly higher than that of an individual blogger who posts weekly thoughts on buildings and food or the Talking Heads.Switching some of your WordPress tables, such as the highly dynamic ones like wp_comments, to the InnoDB storage type can create performance improvements, and therefore scalability benefi ts. Additionally, MySQL also has a confi guration fi le that can be tuned to match your environment. Again, this is really enterprise level tuning of your MySQL. The average site probably is not going to dive into the underlying database storage engines, but an enterprise that has extensive infrastructure on MySQL will have the expertise to make the appropriate adjustments for scaling and performance.Regular Maintenance Finally, your MySQL database needs to be maintained. From time to time, you should run checks on your database tables and optimize and repair if needed. Maintaining your database is like changing the oil in your car or defragmenting your hard drive — you have to do it regularly to keep everything running smoothly. This can easily be done through PHPMyAdmin or another MySQL interface. Plugins such as WP-DBManager by Lester Chan (http://wordpress.org/extend/plugins/ wp-dbmanager/) allow you to schedule these tasks, as well as backups, and not have to worry about it again. c15.indd 388 12/6/12 1:26 AM Scalability ❘ 389Hardware Scaling Now on to the expensive options, adding more hardware. A default WordPress installation is all encapsulated on one machine. This machine functions as both the web server and database, as shown in Figure 15-1. This is the simplest and most basic WordPress hardware scenario. Many, if not most, sites run this way. The next option is to split the database and web server functions into two servers, Web & as shown in Figure 15-2. This allows each server to focus on a specifi c task and is Database the next logical step when your hardware starts to get taxed by the workload. At the same time, make sure that you account for the independent database and FIGURE 15-1: web hosts when you create your WordPress confi guration fi les; you’ll need to WordPress on know the name of the database host because it’s no longer the “localhost” with one server respect to the web server. This is common web application architecture and is very easy to implement with only a few confi guration changes. Again, make sure you re- tune your database and web server software to run on their now independent boxes. Web Moving forward this can get confusing, and the possibilities are endless, so you are only going to briefl y review some common scenarios. Depending on your existing infrastructure, you may have other options available. You may need to do some investigative forensics to determine your next step. That Database is, really fi gure out what the bottleneck is. Regrettably, this can be a reactive plan of attack rather than a proactive one. So, while preparing to scale out your site, FIGURE 15-2: invest some time in some server monitoring infrastructure. You can also do some WordPress load testing using tools such as Apache Benchmark to see how your current infra- on two servers structure performs and make some educated guesses on where the problems might develop. Generally, the next step in scaling is to load-balance your front-end web servers, as shown in Figure 15-3. In this scenario, you deploy two web servers with identical copies of the WordPress installation and use a single database server to store all the data. You have a couple of challenges with this approach. First, you need a load-balancing mechanism. This can be a hardware appliance Web Web or a software solution. You have many different load-balancing mechanisms to choose from, and your infrastructure will dictate which you choose. Enterprises typically have well-established network infrastructure for virtual IP and load-balancing, and any Database horizontal scaling topology should fi t into that IT approved plan.The second challenge is that you will need to synchronize your FIGURE 15-3: WordPress with wp-content/uploads folder. That is, if a content creator uploads load-balanced web servers media onto one server, because the front ends are load-balanced, the next request could pull from the other server where the fi le does not exist. You have the option of moving the uploads folder to a common location, perhaps on the shared database server, or you can set up a scheduled task to copy the fi les across. The rsync (http://www.samba.org/rsync/) utility is a good solution for this type of synchronization. You will have to accept that the fi les will not be there until after the copy has occurred. This means that c15.indd 389 12/6/12 1:26 AM 390 ❘ CHAPTER 15 WORDPRESS IN THE ENTERPRISE there can be a lag between when new content is published and when it is available on both nodes of the web front-end. Some of this lag can be mitigated through a front-end caching mechanism such as the Super Cache plugin. The next scenario for scaling means adding a second database Web Web server and implementing MySQL replication. You continue to keep the load-balanced web servers, but now you have two database servers, as shown in Figure 15-4. Technically, this does not offer better performance, but it does Database Database offer the ability to failover should the database server have a problem. This standby database server is called a hot spare. That means it is on and up-to-date, but not in current use. Part of scal- FIGURE 15-4: WordPress with a hot spare database server ability is availability. Now, you have two web servers and two database servers, which means you can remove one server from each tier and still have a functioning site. Putting that second database into active work on the website is the next layer up. You still have load- balanced web servers, but now you can distribute the load on the database servers using MySQL replication, as shown in Figure 15-5. In this situation you want the writes to the database to be written to the master MySQL database, and all the reads to come from the slave MySQL database. This solves the MyISAM challenge where the storage engine excels at reading or writing but not both. Finally, another WordPress-specifi c option to consider is HyperDB (http://codex.wordpress.org/HyperDB). HyperDB was Web Web designed by Automattic and is a drop-in replacement for the standard WordPress database access layer. It is, however, more powerful than the standard access objects because it can support sharding or partitioning of the WordPress database information Read Write across multiple databases. This can permit you to move the highly Database Database dynamic data to a more robust server, while the content that is less in fl ux can be used on a database server with more aggressive FIGURE 15-5: WordPress with caching. HyperDB also supports replication and failover function- load-balanced web and database ality. However, the documentation is sparse, so implementing this servers solution is not for the faint of heart. In the real world, this is how we run some high-traffi c, higher-profi le sites for our clients. We combine load-balanced web front-ends with caching plugins, each of which reads the content from its own individual slave database server. All writes to the database are written to the master database server and replicated to the slaves. All uploaded content is duplicated to the other web front-ends through an rsync-like process. c15.indd 390 12/6/12 1:26 AM Integration with Enterprise Identity Management ❘ 391INTEGRATION WITH ENTERPRISE IDENTITY MANAGEMENTAs more applications move to the web, a common problem is the proliferation of usernames and passwords. This issue is complicated by requirements for secure passwords that are diffi cult to remember. The increase in access credentials is a known concern and there are many ways to deal with it, including using password-safe or vault applications, or consolidating credentials into Identity Facilities. WordPress’ extensibility makes integrating with outside identity providers relatively easy, and many plugins do just that. The following sections look at two common methods that can be implemented in a company-wide environment.LDAP and Active Directory A common identity provider in a business environment is Microsoft Active Directory (AD), which is a form of the Lightweight Directory Access Protocol (LDAP). Active Directory is what a Windows- based network uses to centrally manage workstation usernames and passwords. It can be much more, but for the purposes of this discussion, you really only care about the username, passwords, and access rights. Assuming you have this in place already, why not use this same central repository to access your WordPress installation? After all, it is the username and password your users are already using to log in to their workstations. The Simple LDAP Login plugin by Clifton H. Griffi n II (http:// wordpress.org/extend/plugins/simple-ldap-login/) does just that. Installation is relatively straightforward, as with most plugins. However, this plugin does not check whether LDAP is currently enabled in your PHP installation, so before proceeding, edit your php.ini fi le and uncomment the LDAP extension to activate it.//for Windows extension=php_ldap.dll //for Linux extension=ldap.soAfter restarting your web server to load your new PHP settings, proceed to activate the plugin and visit the plugin settings page. On this control panel, you will be able to enter your LDAP settings. You will also fi nd a handy testing section to verify your connectivity. The advanced settings are very important for this plugin, as shown in Figure 15-6. Depending on your needs, you will have to carefully consider the Login mode. If your LDAP users are not already provisioned as WordPress users, choosing one of the “Create WordPress accounts” options makes sense to mirror some or all of your LDAP user base into your WordPress installation. You can also use the advanced settings to permit only a specifi ed organizational unit in Active Directory to have login privileges. This is a nice feature to centralize your access and authorization into the already established Active Directory structure. c15.indd 391 12/6/12 1:26 AM 392 ❘ CHAPTER 15 WORDPRESS IN THE ENTERPRISEFIGURE 15-6: Advanced settings for the Simple LDAP pluginSeveral other LDAP/AD plugins are available, so you may want to evaluate them before picking a solution. Be sure to check if the plugin supports secure Active Directory access if that is a requirement of your organization.OpenID and OAuth Active Directory is a specifi c implementation to a Microsoft-centric network. Commercial LDAP products and their open source OpenLDAP cousin are often used as a common user authorization and authentication system where federation of multiple, department-level managed identity systems is required. In either case, this internal enterprise scale authorization is not seen on the wide-open Internet. OpenID was developed as a platform-neutral way to manage authorization in a distributed way. Sounds fancy, does it not? OpenID is set up so that an end user can use the same credentials, in the form of a unique URL and password, and access any application that consumes OpenID for authentication. OpenID is a little different than the traditional username and password credentials most people are used to. With OpenID, you use a unique URL instead of the conventional username. Because it is an open standard, anyone can be an OpenID provider, including WordPress.com, but you can also become your own OpenID provider. If your organization does not already have a central authentication or identity facility, OpenID may be a viable option. Otherwise, it is still a nice add-on for your users, because it allows them to manage their own access credentials in their own central location, if they choose to.The OpenID plugin by the DiSo Development Team (http://wordpress.org/extend/plugins/ openid/) is a simple way to add OpenID functionality to your site. It’s an older plugin, but because c15.indd 392 12/6/12 1:26 AM Content Integration via Feeds ❘ 393OpenID is a standard, the plugin has not needed to be updated and it still works. After activating the plugin, your WordPress login screen and comment screens will be modifi ed to include an OpenID input fi eld, as shown in Figure 15-7. This plugin includes a settings control panel to manage the specifi c features, including auto-approving OpenID published comments. In addition, this plugin has the ability to enhance your WordPress installation to be an OpenID provider by using your author pages, which is a very nice feature. While OpenID federates user identifi cation data, the emerging OAuth protocol allows applications to create and share specifi c authentication actions. OAuth has been frequently described as a “valet key” service for applications, granting limited sets of capabilities to selected users. Signing into one service that uses OAuth such as Facebook, Twitter, or even WordPress.com will create permissions to access or use another service; there is no setup involved for FIGURE 15-7: OpenID-enabled WordPress login the user. page This simplicity has helped OAuth gain popularity with larger social web sites at the expense of OpenID. While this trend exists on the public-facing web, OAuth is probably not an appropriate authentication mechanism for an enterprise deployment of WordPress. Note that WordPress.com uses OAuth to allow applications to interact with the site; it grants permissions to third party applications. If your enterprise WordPress installation is going to be accessed by a variety of mobile and desktop applications to extract, load or update content, then adding an OAuth provider capability may be in order. The few plugins that perform this function are largely in the experimental state, but they are expected to mature over time. On the other hand, if your users are content with the WordPress web based interface, and you don’t plan to make WordPress more of a general purpose back-end CMS, you don’t need to think about OAuth. CONTENT INTEGRATION VIA FEEDSIn one situation we’ve encountered, we managed many sites, normally a subdomain for each department. In this example, each department functions as its own business unit. There are alternatives, but for various reasons, each site became a unique WordPress installation; today you would probably do this with WordPress Multisite. One of the challenges then faced is the duplication of content across multiple sites. Maintaining changes across these separate sites means you have to update a specifi c content piece many times. For example, press releases usually involve multiple departments, or at the minimum, need to be published on the fl agship corporate site as well as the individual department site. c15.indd 393 12/6/12 1:26 AM 394 ❘ CHAPTER 15 WORDPRESS IN THE ENTERPRISEIn short, the business challenge was to reduce multiple manual updates, which are time-consuming and error-prone. Luckily, you have WordPress. One of the easiest ways to integrate content is by using the built-in RSS (really simple syndication) feeds. This is a core feature of WordPress and you will likely fi nd it to be a tool you frequently use. Our solution was to publish all press releases on a central site. In this case, the parent site became our one true location to publish press releases. Press releases are published just like regular posts, and are then assigned to a specifi c category for each department.Each departmental WordPress site has the FeedWordPress plugin (http://wordpress.org/extend/ plugins/feedwordpress/) by Charles Johnson installed. This wonderful plugin takes any RSS or Atom feed and converts it into posts on the site. This is where the magic really happens. WordPress automatically creates RSS feeds for any fi ltered view, such as posts by category or tag, on the originating site. So, for this to work, you use the category RSS feed from original site like http:// example.com/category/press/department/feed. Once you get the plugin installed and activated, you simply enter the URL of the originating feed and schedule the syndication to your website. FeedWordPress has several customizable settings to tailor the category, author, and tag information for the incoming feed, which makes this a very powerful plugin. This works well and allows our content creators to publish to one WordPress location yet have the content distribute out to the additional sites, saving time and energy while also improving accuracy and timeliness of the content. Consider another example of WordPress solving a business need. Our company has two separate web development teams; one focuses on PHP and the other focuses on .NET technologies. In this example, a specifi cation change to a pre-existing ASP.NET application required that it contain regularly updated content pieces. In the current development cycle, changing these content pieces meant rebuilding and redeploying the entire application to the multiple load-balanced servers each time this content changed. An alternative was to develop a minimal content management application to integrate with the existing code and permit content creators to manage the content dynamically. Through no fault of the developers, the development time to add this relatively simple system exceeded the constraints of the project (time, resources, money — pick one). WordPress excels at content origination. Although you could have installed a new .NET RSS syndi- cating web application, you chose to capitalize on an existing WordPress site to manage the dynamic content on the .NET application side. The .NET development team simply had to refactor an RSS consumer object to process a specifi c RSS feed and display the contents in the web application. Our content creators could then use a tool that they were already familiar with to publish the content whenever they needed to. This is a specifi c example of the content management system applications of WordPress discussed in Chapter 14, set in an enterprise context where content publication and origination are the challenges. WordPress certainly can address business needs. Does that mean WordPress is enterprise class software? It does to us. The critical features are WordPress’ own inherent characteristics that fulfi ll certain defi ciencies or improve processes in your business coupled with its robust ability to integrate c15.indd 394 12/6/12 1:26 AM Summary ❘ 395 with other services. This uncanny ability for WordPress to both stand alone and blend into an existing infrastructure makes it an ideal problem solver.SUMMARYAs enterprise needs for specifi c software capabilities continue to grow, WordPress comes up for consideration again and again. WordPress has many features, as outlined in this chapter, that make it accessible on an enterprise scale, including low cost, ease of use, and authentication system integrations, and it is built on well understood platform that IT departments may already have implemented. The next chapter will delve into the WordPress community and how you as a developer can get involved and give back to this great product. c15.indd 395 12/6/12 1:26 AM c15.indd 396 12/6/12 1:26 AM 16 WordPress Developer CommunityWHAT’S IN THIS CHAPTER?➤ Contributing to the WordPress project ➤ Using the Trac software ➤ Working on the WordPress core using Subversion ➤ Exploring valuable WordPress resources for further learningThe WordPress community is what truly makes WordPress. As an open source project, WordPress is continually developed for and by the community, and without community support the WordPress project would dry up and eventually development would cease. By getting involved, you can help make WordPress the best open source software package on the market. This chapter discusses the different methods by which you can contribute to the WordPress project. It also covers some valuable WordPress resources to help expand your knowledge of WordPress and how it works.CONTRIBUTING TO WORDPRESSYou can contribute to the WordPress project in many different ways. The most obvious way is to help with the source code that powers WordPress. Helping with the code can include fi nding and testing bugs, creating patches to fi x bugs and add functionality, and helping test the patches against the latest WordPress trunk. c16.indd 397 12/6/12 1:27 AM 398 ❘ CHAPTER 16 WORDPRESS DEVELOPER COMMUNITYUnderstanding Trac Trac is the open source bug-tracking and project management software used to develop the WordPress project. You can visit the offi cial WordPress Trac website athttp://core.trac .wordpress.org/. Trac is an easy way to create and discuss tickets regarding WordPress. Whether it is a bug report, feature request, or enhancement, Trac helps in creating these tickets and having discussions around them. Have you ever had a new feature idea that you thought would be perfect for WordPress? The easiest way to start that conversation with the WordPress core Developer team is to create a feature request ticket in Trac. Have you ever found a bug in WordPress that keeps appearing in every new version? Creating a bug report is the quickest way to get the issue resolved in the next version. Even if you aren’t a developer, creating tickets and getting involved in the discussions will ultimately help WordPress grow in a positive way!Bug Reporting All software has bugs and WordPress is no different. All open source projects such as WordPress need help from the community to identify and fi x bugs. Fortunately, by utilizing Trac, WordPress makes it very easy to report any bugs you might come across. The fi rst step in reporting a bug is to verify that the bug is, in fact, a bug in WordPress and not a plugin or theme issue. The easiest way to accomplish this is to post the bug in the WordPress Support Forums. You can also discuss the bug in the #wordpress IRC channel, or post a question to the Testers and Hackers mailing list. Finally, you can search Trac to confi rm that the bug you are reporting doesn’t already exist in Trac. After you have confi rmed that the bug exists, it’s time to create a new ticket in Trac detailing the bug. To report a new bug in Trac, you fi rst need to log in. The Trac login account is synced with your WordPress.org account so you can use the same account to log in. If you don’t have an account, you can create a new one at the WordPress.org Support Forums. After logging into Trac, click the New Ticket link at the top. You’ll be presented with a form to fi ll out to submit the new bug ticket. Fill in the following fi elds on the new ticket: ➤ Summary — Short but accurate and informative title summarizing your bug ticket. ➤ Description — Detailed description of the bug. Include steps to reproduce the bug and add an example URL displaying the bug if possible. Also include platform versions such as operating system, web server, PHP version, MySQL version, and WordPress version. ➤ Ty pe — The type of ticket you are submitting. In this case, use the default of “defect (bug)” but other options are available. ➤ Version — The version of WordPress in which the bug was found. This applies to bug tickets only and not new feature requests. ➤ Keywords — Tags used to describe your ticket. Some standard keywords are covered in the following section. ➤ Assign to — Trac username responsible for fi xing the bug. If you plan to fi x the bug yourself, you can list your username here. c16.indd 398 12/6/12 1:27 AM Contributing to WordPress ❘ 399➤ Component — The component in WordPress where the bug was found. ➤ Severity — The signifi cance of the issue. Most bugs would use the default of Normal. ➤ Cc — You can Cc yourself on all ticket updates by adding your Trac username or e-mail address to this fi eld.After you have fi lled in all of the new ticket information, and previewed the ticket to verify that it’s correct, click the Create Ticket button to create a new Trac ticket. If you have any attachments to upload, such as a screenshot of the bug, check the box next to “I have fi les to attach to this ticket.” On the following screen, you will be allowed to upload any fi les attachments you would like.Trac Keywords In Trac, a number of defi ned keywords are commonly used for WordPress tickets. These keywords are used for reporting to make fi nding tickets easier. Following is a list of these keywords and their appropriate usage: ➤ has-patch — A solution patch fi le has been attached to the ticket and is ready to be tested before committing to the core of WordPress. ➤ needs-patch — The ticket has been confi rmed and a patch is needed to fi x the problem. ➤ needs-refresh — The patch no longer applies; it needs to be merged and resubmitted. ➤ reporter-feedback — Additional feedback is needed from the ticket creator. ➤ dev-feedback — A response is needed from a developer. ➤ 2nd-opinion — A request for a second opinion is needed regarding the problem or solution. ➤ close — The ticket is a candidate for closure. ➤ needs-testing — Someone needs to test the solution. ➤ ui-feedback — Response is needed from the WordPress UI Group. ➤ ux-feedback — Response is needed from the WordPress UX Group. ➤ needs-ui — The ticket requires updates to the visual appearance of one or more items. ➤ needs-unit-tests — Unit tests needed to verify and test any patch that may exist. ➤ needs-docs — Inline documentation for the code is needed. ➤ rtl-feedback — Feedback is needed regarding Right-to-Left language support (RTL). ➤ needs-codex — Documentation in the WordPress.org Codex needs to be updated or expanded.By adding the correct keywords, your ticket will automatically be included in Trac reports created for WordPress. For example, the has-patch report shows all tickets with the has-patch tag: http://core.trac.wordpress.org/report/13. These reports are extremely useful if you want to help contribute to WordPress. c16.indd 399 12/6/12 1:27 AM 400 ❘ CHAPTER 16 WORDPRESS DEVELOPER COMMUNITYView and Search Tickets Trac features many different ways to search and fi lter through the tickets available. To view Trac tickets, click the View Tickets link at the top. The next screen displays multiple predefi ned searches for fi ltering tickets. To view all tickets in Trac, click the All Tickets link in the Trac menu. The list of all active tickets can be a bit overwhelming because there are usually hundreds of tickets in Trac. To make Trac more manageable, some predefi ned reports have been created to help fi lter the tickets down. Following is a list of the most commonly used reports in Trac: ➤ All Tickets — Displays all tickets in Trac. ➤ Next Minor Release — Tickets assigned to the next minor release (3.5.x). ➤ Next Major Release — Tickets assigned to the next major release (3.x). ➤ Commit Candidates — Tickets that have been tested. ➤ Has Patch / Needs Testing — Lists all tickets with a patch that need to be tested and verifi ed to fi x the ticket issue. ➤ Needs Patch — Lists all tickets needing a patch. ➤ Latest Tickets — Displays the latest tickets submitted to Trac. ➤ My Tickets — All tickets created by you.You can also create your own custom search queries within Trac. To do so, click the small Custom Query link that appears after you click View Tickets. By default, the Custom Query page displays all open tickets in Trac. To refi ne this list with your custom query, you are going to add a fi lter. To the left of the screen is a drop-down select box with different fi lters. For this example, select Milestone. After you select Milestone, the fi lter appears under the Filters section across the top of the page. Here you can select the Milestone you want to view tickets for. Select the next version of WordPress to be released to view all tickets assigned to that Milestone, as shown in Figure 16-1.FIGURE 16-1: Custom Query in TracThe number of open tickets is always a good indication of how close the new version of WordPress is to being released. You can add multiple fi lters to your custom query. For example, you could add a fi lter for the needs-testing keyword to fi lter the tickets to show all tickets that need to be tested for the upcoming version of WordPress. c16.indd 400 12/6/12 1:27 AM Contributing to WordPress ❘ 401Trac Timeline Trac also features a timeline of all recent activity within the system. This is great for a top-level overview of what changes have happened in Trac daily. You can also fi lter the date range and ticket status. To view the Trac timeline, visit http://core.trac.wordpress.org/timeline.Browsing Source One of the major advantages of the Trac software is how it integrates with Subversion (SVN). Subversion is the version control software used by WordPress to track code changes and commits. Within Trac, you can view the most current version of the WordPress software, which is sometimes referred to as bleeding-edge. To view the current WordPress source, click the Browse Source link in the Trac menu. The current version of WordPress is located in the trunk folder. Viewing the WordPress source in Trac is extremely useful for seeing new changes made to WordPress. Next to each fi le the Last Change is listed and linked to the Trac ticket that has details about that change. The Age is also listed, showing the date when the fi le was last edited.Notice at the very bottom of the page that there is a link: Download in other formats: Zip Archive. Just click this link to download the entire bleeding-edge copy of WordPress. After downloading WordPress from Trac, you can install it on your own server just like a normal installation of WordPress. This is great for testing out new features in the upcoming version of WordPress. Keep in mind that this is bleeding-edge software so bugs will most likely exist. You wouldn’t want to run this version of WordPress on a production website.Working on the Core The WordPress software is built by the community, which means anyone can help contribute to the codebase. When someone says WordPress is built by the community, it doesn’t mean that anyone can go edit the WordPress source code. To contribute to the WordPress core, you must create a patch fi le with your changes and submit that fi le for review. If accepted, your changes will be incorporated into the WordPress core and will be included in the next version release. Contributing code edits, bug fi xes, and additional functionality is done using Subversion. It was stated rather emphatically in Chapter 2 that you should never hack core. In this case, you aren’t actually hacking the core of a WordPress installation, but rather creating patch fi les to submit for inclusion into the WordPress software.Understanding Subversion Subversion is used to make modifi cations to the current codebase and generate patch fi les. A patch fi le is a text fi le that contains the changes that were made to a specifi c fi le or fi les. To work on the WordPress core you will need to generate patch fi les and submit them for review. Once a patch fi le has been accepted as the best fi x for the issue, it will be committed to the WordPress core code.Hook into the WordPress core The fi rst step in hooking into the WordPress core is to check out (download) the latest codebase using SVN. To do so, you’ll need an SVN client on your development machine. For the rest of this chapter, you’ll consider examples that use the TortoiseSVN client, which is one of the more popular c16.indd 401 12/6/12 1:27 AM 402 ❘ CHAPTER 16 WORDPRESS DEVELOPER COMMUNITY choices for Windows. The WordPress SVN repository is located at http://core.svn.wordpress .org/trunk/. Checking out a repository creates a copy of it on your local machine. This is the copy of WordPress you will modify when fi xing bugs and adding new functionality. Using TortoiseSVN, right-click the folder you want to download the WordPress codebase to and select SVN Checkout. Make sure to fi ll in the SVN repository URL for WordPress and click OK to download the codebase. For more information on using Subversion with WordPress, check out http://codex.wordpress.org/Using_Subversion.Create a patch/diff File Now that you have downloaded the WordPress codebase, it’s time to make some changes! Pick any fi le you want to modify and make the appropriate changes as needed. Make sure to save the fi le after you are fi nished making edits. Now you need to create a patch fi le that details the changes you made. To do so, right-click the fi le you modifi ed and select TortoiseSVN ➪ Create Patch. A dialog box appears, allowing you to select the modifi ed fi les; in this case, only one fi le should appear, so click OK to proceed. Next, choose a location to save your patch fi le to and give it a unique name. It’s a good practice to name your patch fi le the same as the fi le you edited, so if you modifi ed wp-config-sample.php, name your patch fi le wp-config-sample.patch, and click Save. You have just successfully created a working patch fi le for WordPress! This patch fi le can be submitted to any Trac ticket as a bug fi x or feature recommendation. If the patch is accepted, a core WordPress Committer will commit your patch fi le to the core of WordPress. After a patch you have submitted has been accepted into the WordPress core, you can offi cially call yourself a WordPress core Contributor!Submitting Plugins and Themes Submitting plugins to the Plugin Directory is the best way to release a plugin to the public. This also holds true for submitting themes to the Theme Directory. Ultimately you want as much exposure as possible for any theme or plugin that you release. Adding your plugin and theme to the appropriate WordPress.org directory is the best way to accomplish this. Remember that both directories are hooked in the admin side of every current installation of WordPress. This means anyone running WordPress can easily install your theme or plugin with just a few clicks. To submit your theme or plugin, visit the offi cial submission page on WordPress.org:➤ Plugin submission — http://wordpress.org/extend/plugins/add/ ➤ Theme submission — http://wordpress.org/extend/themes/upload/Here you’ll fi nd instructions on the proper submission process for both. The submission process is covered in more detail in Chapter 8, “Plugin Development.”Documentation Documentation is a thankless job, yet nearly every developer relies on the documentation at some point. A great way to contribute to the WordPress community is to help keep the documentation updated. Assume that every time a new WordPress release comes out, the documentation needs to be updated to refl ect the changes, whether new functionality is added, behavior is modifi ed, or certain aspects are scheduled for deprecation. c16.indd 402 12/6/12 1:27 AM Sister Projects ❘ 403Keeping the documentation current is a daunting task, and given the volunteer nature of the project, is sometimes neglected. You can often fi nd out-of-date information in the Codex for WordPress releases from long ago that are no longer best practices, applicable, or even supported. Documentation updating is not glamorous — it is not the shiny new functionality and features that everyone is excited about — but it is one of the best ways to support the community and help new users. Sometimes, solid documentation is what draws new developers in and helps keep them in the community. If you are interested in helping out with the WordPress documentation, please subscribe to the Documentation Mailing list at http://codex.wordpress.org/Mailing_Lists#Documentation.SISTER PROJECTSWordPress has a few different sister projects currently available. These software projects are considered sister projects because they are developed in much the same way as WordPress. Many of the developers behind these projects also contribute to the WordPress project. Sister projects are also built as plugins, which makes WordPress integration simple and easy.BuddyPress BuddyPress is a plugin that adds a social networking layer to WordPress. BuddyPress can be themed to match your current website design. Some of the features available include extended profi les, private messaging, friend connections, user groups and activity streams, status updates, forums, and more! All BuddyPress features are independent, meaning you can enable just the features you want and not the entire BuddyPress suite. For more information on BuddyPress visit http://buddypress.org. bbPress bbPress is an open source forum software plugin. The goal of bbPress is to be lightweight, powerful, fast, and easy to use. bbPress has many of the features you would expect from message board software, including a simple interface, customizable templates, and spam protection. bbPress can also run plugins to extend its functionality just like WordPress. bbPress was originally offered as a separate installation package, but has since been ported over to a WordPress plugin. You can download bbPress at the offi cial Plugin Directory page, http://wordpress.org/extend/plugins/ bbpress/ or learn more about bbPress at http://bbpress.org.Future Projects WordPress is growing at an amazing rate and new projects are always popping up. It’s hard to imagine what new projects you’ll see in the future, but if WordPress has taught us anything, it’s to expect the unexpected. c16.indd 403 12/6/12 1:27 AM 404 ❘ CHAPTER 16 WORDPRESS DEVELOPER COMMUNITYRESOURCESMany different resources are available for WordPress. This section provides a list of the most popular resources that you should be aware of to expand your knowledge of WordPress.Codex The WordPress Codex is one of the largest and best resources available for WordPress, and is essentially an online manual for WordPress users. Powered by MediaWiki, the Codex is a wiki- style documentation project, meaning anyone can contribute to the articles and content featured. Featuring tutorials, examples, function references, and much more, the Codex takes you through everything from installation to customization. The offi cial site is http://codex.wordpress.org/ Main_Page.Support Forums The WordPress Support Forum is another great resource. You can visit the support forum at the offi cial URL: http://wordpress.org/support/. The support forum is powered by bbPress, the forum plugin mentioned in the previous section. The support forum is separated into multiple sections covering many different topics. The quickest way to locate related threads is to search the forum using the Search box. There is also a tag cloud powered by hot topics in the forum. This can be a quick way to see what the trending topics are in the forum. Forum threads can also be tagged with keywords about the post. Any post tagged with the name of a plugin is automatically added to the plugin’s support forum. The new forum post will be counted under the Support section in the right sidebar on the plugin detail page, as Figure 16-2 shows. This provides a support forum section for every plugin in the repository. To create a forum post about a plugin, just add the plugin slug as a tag on your post. For example, to create a post about the WordPress Custom Post Type UI plugin, you would tag your forum post with custom-post-type-ui, which is the slug from the plugin URL: http://wordpress.org/support/plugin/custom-post-type-ui. You’ll also notice the Compatibility section shown in Figure 16-2. This FIGURE 16-2: See what oth- allows users of the plugin to verify if the plugin works with their ers are saying version of WordPress. If enough people report that the plugin is broken, it is probably not a stable enough plugin to use. Forum posts can also be marked as resolved. If you post a question and someone replies with a response that helps you resolve your problem, you should mark your post as resolved. This will add the text [resolved] to the front of your post topic to let others know the problem has been resolved. This helps other community members fi nd answers to their questions by viewing the resolved threads. c16.indd 404 12/6/12 1:27 AM Resources ❘ 405WordPress Chat WordPress has some very active chat rooms on IRC (Internet Relay Chat). To join a WordPress chat room you will need to install an IRC client on your computer. Once an IRC client is installed, you can connect to the Freenode server at irc.freenode.net, and once you have connected, you can join one or more of the chat rooms listed here: ➤ #wordpress — The primary WordPress chat room. Great place to get questions about WordPress answered quickly and accurately. ➤ #wordpress-dev — Chat room dedicated to WordPress core development. Topics are restricted to working on the WordPress code itself and not for general WordPress inquiries. ➤ #wordpress-themes — Chat room for the theme review process. ➤ #wordpress-ui — Chat room for the WordPress UI Group. ➤ #<a href="/tags/BuddyPress/" rel="tag">buddypress</a>-dev — Chat room dedicated to all BuddyPress-related conversations. ➤ #bbpress — Chat room dedicated to all bbPress-related conversations.These IRC chat rooms are a great resource for getting real-time help. Many WordPress experts hang out in these rooms regularly and love to help out other WordPress enthusiasts. This is also a great place to expand your knowledge of WordPress.The WordPress core developers host a weekly development chat in #wordpress-dev. This scheduled chat covers a preset agenda of topics regarding the future development of WordPress, and many decisions are made on features and functionality in these weekly chats. The topics typically cover features being developed for the upcoming version of WordPress, but can also cover additional items. For more information on IRC and WordPress chat rooms, visit the offi cial Codex IRC page at http://codex.wordpress.org/IRC. This page details how IRC works, how to download and install an IRC client, how to connect to an IRC server, and also how to join a WordPress chat room.Mailing Lists WordPress has multiple mailing lists focused on different topics of the WordPress project. Most mailing lists are two-way conversations, meaning that an e-mail is sent to the list with a problem or question, and another member of the mailing list responds with the answer. Anyone subscribed to that mailing list will be able to track the conversation. To register for any mailing list, just visit the corresponding join link. Available mailing lists include: ➤ Announcements — List for major announcements regarding WordPress. E-mail is very low frequency and one-way, meaning no conversations can take place. ➤ How to Join — Edit your WordPress.org profi le and select Subscribe to WordPress Announcements under Mailing Lists. ➤ Documentation — List for coordinating and collaborating on WordPress Codex documentation. If you plan on contributing to the Codex, this list is a must join. c16.indd 405 12/6/12 1:27 AM 406 ❘ CHAPTER 16 WORDPRESS DEVELOPER COMMUNITY➤ E-mail — wp-docs@lists.automattic.com ➤ How to Join — http://lists.automattic.com/mailman/listinfo/wp-docs ➤ Hackers — Primary mailing list for discussions on extending through plugins or core code modifi cations. Many discussions revolve around core functionality of WordPress. ➤ E-mail — wp-hackers@lists.automattic.com ➤ How to Join — http://lists.automattic.com/mailman/listinfo/wp-hackers ➤ Testers: Discussions regarding the current nightly, alpha, or beta version of WordPress. ➤ E-mail — wp-testers@lists.automattic.com ➤ How to Join — http://lists.automattic.com/mailman/listinfo/wp-testers ➤ XML-RPC — Discussions revolving around the XML-RPC topic of WordPress. ➤ E-mail — wp-xmlrpc@lists.automattic.com ➤ How to Join — http://lists.automattic.com/mailman/listinfo/wp-xmlrpc ➤ Support Forum Volunteers — Discussions involving WordPress Forum Support and providing support to users. ➤ E-mail — wp-forums@lists.automattic.com ➤ How to Join — http://lists.automattic.com/mailman/listinfo/wp-forums ➤ SVN Updates — List for tracking SVN repository updates. E-mail is sent for every update along with information on the changes made. SVN is the version control system WordPress core developers use to track changes in the WordPress core fi les. ➤ E-mail — wp-svn-bounces@lists.automattic.com ➤ How to Join — http://lists.automattic.com/mailman/listinfo/wp-svn ➤ Trac — List for tracking changes in Trac, the open source bug tracking system WordPress uses for tracking development on the WordPress core. This is a very high-traffi c e-mail list. ➤ E-mail — wp-trac-bounces@lists.automattic.com ➤ How to Join — http://lists.automattic.com/mailman/listinfo/wp-trac Certain WordPress mailing lists can be high traffi c, so it’s a good idea to create a rule in your e-mail program to automatically fi lter WordPress mailing list e-mails to a specifi c folder. That way, you can review the conversations taking place at your leisure. To subscribe to any of these mailing lists, or for more information, visit the offi cial Codex mailing list page at http://codex.wordpress.org/Mailing_Lists. To view all available mailing lists, visit the offi cial Automattic mailing list page at http://lists.automattic.com/mailman/listinfo.External Resources There are many external resources for WordPress outside of WordPress.org. Following is a list of the most common: c16.indd 406 12/6/12 1:27 AM Resources ❘ 407➤ WordPress Hooks Database (http://adambrown.info/p/wp_hooks) — Website detailing all hooks (actions and fi lters) in WordPress by version. Great for referencing latest hook additions when a new version of WordPress is released. ➤ PHPXref for WordPress (http://phpxref.ftwr.co.uk/wordpress/) — Features cross-reference code library for WordPress. Use to easily view all variables, functions, classes, and constants used in WordPress. Xref shows where each item is defi ned as well as where it is referenced through the WordPress code. WordCamp and Meetups WordPress is powered by the community behind it and because of that the community loves to get together and talk WordPress! This can happen a number of different ways but the two most popular events are WordCamps and WordPress Meetups. WordCamps conferences focused on anything and everything WordPress. These events usually have hundreds of attendees and multiple tracks for speakers with a wide array of topics. If you are interested in WordPress at all, these are must-attend events. To fi nd a WordCamp in your area, visit the offi cial WordCamp Central website at http://central.wordcamp.org/. WordPress Meetups are smaller local-based gatherings. These are usually informal get-togethers where attendees talk WordPress and share their experiences and knowledge with others. WordPress Meetups are typically held monthly or quarterly. To fi nd a Meetup in your area, check out the offi cial WordPress Meetup Groups page at http://wordpress.meetup.com/.WordPress.TV WordPress.TV is a website dedicated to videos about WordPress. The website features tutorials for both WordPress self-installs and WordPress.com. Also featured on WordPress.TV are WordCamp footage and speaker sessions, interviews, and much more. This is a central repository for all videos related to WordPress. WordPress.TV is a great resource for learning more about WordPress through videos. Visit the offi cial site at http://wordpress.tv/.Theme/Plugin Directories The fi rst place to visit after installing WordPress is the Plugin and Theme directories. In the Plugin directory you can download thousands of plugins to add all sorts of amazing functionality to your website. The Theme directory features more than a thousand free themes for WordPress that can be used to give your site a new look. Remember that both of these directories can be browsed from within your WordPress installation.➤ Plugin directory — http://wordpress.org/extend/plugins/ ➤ Theme directory — http://wordpress.org/extend/themes/ WordPress Ideas WordPress.org features an Ideas area for gathering ideas for future features in WordPress. Here you can vote on your favorite ideas and view a list of the most popular ideas based on votes. The most c16.indd 407 12/6/12 1:27 AM 408 ❘ CHAPTER 16 WORDPRESS DEVELOPER COMMUNITY popular ideas are usually reviewed before the development of a new version of WordPress and typically a few of them will make it into the new release. You can visit the offi cial Ideas page at http:// wordpress.org/extend/ideas/.WordPress Development Updates Staying informed with the development of WordPress is a great resource for tracking upcoming WordPress changes and features. As new versions of WordPress are developed and released, they come with new features and functionality. Understanding what these new features are can help with planning new projects for WordPress. The easiest way to do this is at the offi cial WordPress Development Updates site at http://make.wordpress.org/core/. The Make WordPress core site uses the popular P2 theme, which is very similar to a Twitter-like theme for WordPress. The site features updates and discussions on the WordPress project. The site is also the location for information regarding the weekly WordPress Developer Chats in the #wordpress-dev IRC channel. The date and time for these meetings is featured in the sidebar. There is also a post detailing the topics for the weekly meeting. Anyone can contribute topics for the meeting by responding to this post.Make WordPress.org A new resource is http://make.wordpress.org. This section of WordPress.org is a central hub for offi cial resources to help people develop for WordPress. Currently, there are eight sections, which are specifi c to different areas of WordPress: 1. make.wordpress.org/core/ — Blog for the core development team of WordPress. 2. make.wordpress.org/ui/ — Blog for the WordPress UI design group. 3. make.wordpress.org/plugins/ — Blog for announcements and resources for plugin developers. 4. make.wordpress.org/themes/ — Blog for announcements and resources for theme designer and developers. 5. make.wordpress.org/support/ — Blog for support members. This is not a blog for receiving support, but rather, it’s for members who provide support and covers how they can improve the process. 6. make.wordpress.org/polyglots/ — Blog for WordPress translators. 7. make.wordpress.org/accessibility/ — Blog for the WordPress accessibility group. 8. make.wordpress.org/mobile/ — Blog for announcements and resources for WordPress mobile developers. The sites listed provide an excellent way to get involved in a specifi c area of WordPress.WordPress Podcasts Podcasts are a great way to stay informed on the latest news and information on any topic. Currently, two WordPress-centric podcasts are actively being produced. c16.indd 408 12/6/12 1:27 AM Resources ❘ 409WP Late Night The WP Late Night podcast is a live weekly podcast hosted by Brad Williams (that’s me!), Dre Armeda, and Ryan Imel. The show is created and released on WPLateNight.com. The podcast also streams live video of the shows being recorded so you watch the hosts and guests of the show as they discuss all things WordPress. You can visit the website at http://wplatenight.com.WPCandy.com Shows WPCandy.com has a slew of WordPress-related podcasts. With the Roundtable Podcast, the WPCandy Podcast, the Weekly Theme Show, and more, there’s no shortage of awesome WordPress- related audio content. For a full list of shows and episodes produced by WPCandy.com visit http://wpcandy.com/shows.WordPress News Sites Many different WordPress-related websites exist. This section provides a list of the most popular WordPress-focused sites for news and information regarding anything and everything WordPress-related.WPCandy.com WPCandy.com has become the dominant WordPress news site out there. The site was relaunched in early 2010 by Ryan Imel and has since grown at a rapid pace. With in-depth editorials, detailed tutorials, community member interviews, podcasts, and more, it’s easy to see why WPCandy.com is the resource for WordPress-related news.WPRealm.com WPRealm.com is one of the newer sites in this list. Launched in 2012 by some very prominent community members, WPRealm.com is a blog concerning all things WordPress. The blog also loves contributors and urges anyone interested in writing to submit articles to the website. You can visit the website at http://wprealm.com.WPForce.com WordPress Force is another great website writing about all things WordPress. The website covers WordPress releases, plugin and theme releases and reviews, and much more. You can visit the website at http://wpforce.com.WPEngineer.com WPEngineer features tips and tricks, news, and improvements for WordPress. The site features more in-depth tutorials that dive into the core of WordPress and its functionality. These tutorials are focused on intermediate-level WordPress users and developers. You can visit the website at http://wpengineer.com/. c16.indd 409 12/6/12 1:27 AM 410 ❘ CHAPTER 16 WORDPRESS DEVELOPER COMMUNITYWordPress Alltop Alltop is basically an RSS aggregator for specifi c topics. The WordPress Alltop page features news and information from the top WordPress-related websites. It also lists important WordPress Twitter accounts that are worth following for news and information. You can visit the website at http://wordpress.alltop.com/.WordPress Planet WordPress Planet is an aggregation of blogs writing about WordPress. This includes posts from core contributors and very active community members. This is the same news feed featured on the Dashboard of every default installation of WordPress under the Other WordPress News dashboard widget. Visit the website at http://planet.wordpress.org/.Planet WordPress Planet WordPress is also an RSS aggregator that keeps track of bloggers who contribute to WordPress. This feed differs from WordPress Planet in that it extends the WordPress Planet feed with even more bloggers. These bloggers are mainly plugin developers and core contributors for WordPress. The news feed is maintained by Ozh Richard, a very respected developer in the WordPress community. The website is located at http://planetwordpress.planetozh.com/.SUMMARYIn this chapter you learned the different ways you can contribute to the WordPress project, including using Trac bug-tracking software, working on the WordPress core using Subversioin, and submitting plugins and themes. You also learned about sister projects to WordPress including BuddyPress and bbPress. Finally, you learned about the diverse resources available as you work with WordPress. c16.indd 410 12/6/12 1:27 AM INDEXA add_settings_section(), 166 MAMP, 10, 44, 45, 46, 47 add_shortcode(), 267 permissions, 356–357 absint(), 62, 150, 193, 272 add_site_option(), 63, 276, virtual hosts, 51–53 ABSPATH, 145, 183, 195 277 WAMP, 45, 46, 47, 48, 49, Action hooks, 151–156. See also add_submenu_page(), 158, 51, 213 specifi c Action hooks 159, 161, 275 WAMPSERVER, 45, 47 Action Reference, 156 add_theme_page(), 160 web server caching, 346 activating functions, 142–143 add_user_meta(), 64 APIs (WordPress), 69–71. Active Directory, 391–392 add_users_page(), 160 See also specifi c APIs add_action(), 64, 152 admin_head, 154, 156 API functions, 62 add_blog_option(), 276 admin_init, 155, 161, 166, 279 Appert, Julien, 371 add_comments_page(), 160 Administrator role, 362 architecture of participation, 7 add_dashboard_page(), 160 admin_menu Action hook, 159 archival templates, 231 add_filter(), 64, 151, 152 admin_url(), 146 Archived, site status, 263 add_hook(), 64 AdSense, 78, 304, 305, 306, archive.php, 227–228 adding metadata, 134–135 307, 340 archive-slides.php, 231 add_links_page(), 160 advanced queries, Loops, 91–92 arguments, 117–121, 130 add_management_page(), 160 /advanced-cache.php, 30, 38 array of options, plugins, add_media_page(), 160 advertising, 303–307 157–158, 185 add_menu_page(), 158, 159, advertising plugins, 304–305 array_map(), 280 161, 275, 278 AJAX, 27, 147, 314, 335 Aside, post format, 250 add_meta_box(), 169–170, 188 AJAXy, 378, 379 assets, themes and, 214–215 add_meta_boxes Action hook, Akismet, 2, 58, 113, 352 Attachment, default post type, 170, 188 Allbut, Jonathan, 368 116 add_new, 121 all_items, 131 attachment.php, 233 add_new_item, 121, 131 Alltop, 410 attacks add_option(), 63, 156, 277 Alsup, Mike, 375 brute-force attacks, 354, add_options_page(), 160, 186 alt attributes, 326 355 add_or_remove_items, 131 Alternative PHP Cache, 345 cross-site request forgery, add_pages_page(), 160 Announcements, mailing list, 148 add_plugins_page(), 160 405 cross-site scripting, 70, 150, add_post_meta, 64, 134, 137 Apache 252 add_posts_page(), 160 Directory directive, 47 salt values, 25, 113, 355 add_post_type_support(), document root, 47 SQL injection attacks, 26, 125 $is_apache, 96 106, 111, 148 add_settings_field(), LAMP, 44–45, 346–347 Audio, post format, 250 166, 167 lighttpd, 9, 387 author parameters, 84411 bindex.indd 411 12/6/12 1:09 AM Author role – confi guration fi le, security andAuthor role, 361 buttons, social media, choose_from_most_used, 131 $authordata global variable, 291–293 close, Trac keyword, 399 94–95 cloud computing, 350 author.php, 236–237 CMS. See content management automating spam detection, C system code comments, 58 351–352 cache management. See also code overview, 21–39. See also Automattic, 2, 3. See also scalability .htaccess; wp-config.php Akismet; Twenty Eleven caching hierarchy, 343 breaking code, 222 AUTOSAVE_INTERVAL, 27 enterprise-scale WordPress, directory and fi le structure, AWStats, 338–340 388 23 MySQL query cache, 348 downloading WordPress, object caching, 347 B 21–23 scalability, 343–348 .maintenance fi le, 35–36 b2/cafelog system, 2 transient caches, 301–303, Codex badges, social networking, 347–348, 388 controversy, 71 292–294 web server caching, 343, database changelog, 102 barebones themes, 215 345–347 defi ned, 66, 404 bbPress, 2, 379, 380, 403, 404, WordPress system described, 4–5 405 complexity, 344–345 Function Reference, 67–69, #bbpress, 405 Cameron, Dan, 333 133 beautiful URLs, 321 can_export, 119 template hierarchy fl owchart, Behrens, Kevin, 363, 367 canonical URLs, 76 233–234 Bing.com, 322 Caoimh, Donncha O, 347, 358 using, 66–67 Bio Widget, 175, 176 capabilities argument, 119 WordPress APIs, 69–71 blacklists, 351–352 capability_type, 119 wp-config options, 31 bleeding-edge version, WordPress, capital_P_dangit, 63 coding, for Multisite, 265–287 22, 401 CAPTCHAS, 350–351 collecting external content, Blog ID (site ID), 260, 265–266 Carrington theme, 257 294–303 blogs.dir directory, 37, 38, 261 cascading style sheets. See CSS colors, visual design elements, body_class(), 239 categories 313 Bones theme, 256 parameters, 84 comment_post Action hook, Boring page template, 243 taxonomy, 126 152, 155 Brachhold, Arnie, 321 category.php, 228–230 comment_post_ID, 105, 114 branches folder, SVN, 209 CDN. See Content Delivery comments, spam and, 350–352 Brave New Code, 335 Network comments.php, 237–238 breaking code, 222 cForms 11 plugin, 379 comments_popup_link(), 80 browsers Chan, Lester, 54, 388 comment_text, 153 browser detection Changelog section, readme.txt, commercial situations, WordPress global variables, 95–96 207–208 in, 5–6 WPTouch, 335 character set, 25 commercial themes, 3, 256, 257, caching hierarchy, 343 charset, 25 258 brute-force attack, 354, 355 Chat, post format, 250 community intersection, BuddyPress, 2, 380, 382, chat, WordPress, 405 WordPress, 4–5 403, 405 check_admin_referer(), complexity, WordPress, 344–345 #buddypress-dev, 405 147–148, 190, 280 conditional tags, 223–224 bug reporting, Trac software, child themes, 215–216, 251–256. confi guration fi le, security and, 398–399 See also parent themes 354412 bindex.indd 412 12/6/12 1:09 AM confl ict, advertising content –database class (wpdb class) confl ict, advertising content, roles and delegation, child themes, 252, 253, 254 306–307 367–368 separating concerns, 324 consistent navigation, user theme and widget support, style.css fi le, 217–218 experience, 310–312 370–372 themes, 214 constructor, 176, 192 workfl ow, 368–370 Zen Garden, 324 content. See also pages; posts content organization, CMS, CSS ID attribute, 170 defi ned, 76 370–379 CSS ID name, 176 duplicate, 321–323 content selection, 73, 74, 100. CSS3, 330–331, 335–336 easy to fi nd, 314 See also Loops current_time(), 62 content aggregation, 289–308 content sharing sites, tags and, $current_user global variable, advertising, 303–307 324 95 collecting external content, content tables, 104–105 custom database tables, plugins, 294–303 content_url(), 146 180–182 feeding WordPress upstream, contributing to WordPress, custom meta box, 172–174 292 397–403 custom page templates. See page generic XML data, 299–301 Contributor role, 361 templates getting noticed, 290–291 controversy, Codex, 71 custom parameters, 84 Google Maps, 298–299 conversation, 7–8 custom post types, 116–125 overview, 289–290 COOKIEPATH, 29 Custom Search Engine, Google, privacy and history, 307–308 copyright law, 5 333, 334 social media buttons, core (WordPress core), 57–72. custom settings section, 165–169 291–293 See also Codex custom taxonomies, 128–133 social networking badges, Akismet, 58 custom widget, 178–179 293–294 caching hierarchy, 343 customizing Loop, 75, 81–82 transients, 301–303 contents, 57–58 CUSTOM_USER_META_TABLE, 29 YouTube video integration, deprecated functions, 65–66 CUSTOM_USER_TABLE, 29 295–296 exploring, 62–65 Content Delivery Network functions search, 60–62 (CDN), 315, 350, 387 hacking, 71–72, 382 D content directory, security, 355 Hello Dolly, 58 Dashboard, 17–19, 352, 353 content display, 224–234. hook into, 401–402 Dashboard Widgets, 179–180 See also Loops; theme creation inline documentation, 59, 60 Dashboard Widgets API, 70, 179 archival templates, 231 as reference, 58–66 data validation, 148–151 Loop, 73 themes, 58 database (WordPress database). template hierarchy, 233–234 working on, 401–402 See also database tables content hierarchy, CMS and, create_category, 154 changelog, 102 376–379 cron, 31, 338 data management, 101–114 content management system cross-site request forgery (CSRF), diagram, 101–102 (CMS), 365–382 148 direct manipulation, 111–114 content hierarchy, 376–379 cross-site scripting (XSS), 70, database class (wpdb class), defi ned, 6–7, 365–367 150, 252 106–111 featured content pages, Crowd Favorite, 55, 257, 386 complex database 373–376 crowd sourcing, 317, 318, 352, operations, 108–109 forms management, 367 dealing with errors, 110–111 379–380 CSRF. See cross-site request prepare(), 106–107, 109 forums, 379 forgery simple database queries, homepages, 372–373 CSS (cascading style sheets) 106–108 other systems, 380–382 Bones theme, 256413 bindex.indd 413 12/6/12 1:09 AM Database confi guration dialog box – File Monitor, WordPressDatabase confi guration dialog determining paths, plugins, enhancements, 246–251, box, 12 145–146 330–331 database schema, 101–103, developer community. See enterprise software, 383 287–288 WordPress Developer enterprise-scale WordPress, database tables, 103–106. See Community 383–395 also specifi c database tables developing locally. See local cache management, 388 custom, plugins, 180–182 development environment feeds, 393–395 Multisite-specifi c, 287 development environment, hardware scaling, 389–390 taxonomy table structure, deployment cycle, 42 identity management 126–127 dev-feedback, 399 integration, 391–393 date parameters, 84 Diff/patch fi le, 402 MySQL maintenance, 388 DB_CHARSET, 25 direct database manipulation, performance tuning, DB_COLLATE, 25 111–114 386–388 dbDelta(), 181 directories, WordPress, 23. scalability, 386–390 db-error.php, 235–236 See also specifi c directories when to use, 383–385 DB_HOST, 25 Directory directive, Apache, 47 Erlewine, Michael Yoshitaka, 378 DB_NAME, 25 disconnect, menu management, error level, PHP, 49 DB_PASSWORD, 25 247, 248, 377 error_log, 28 DB_USER, 25 DiSo Development Team, 392 errors, wpdb class and, 110–111 deactivate plugins, 37 DNS, 51, 349 escaping functions, 111, 148–149, deactivating functions, do it yourself installation, 10–17. 177 142–143 See also WordPress esc_attr(), 63, 149, 177 debugging Doctorow, Cory, 5, 7 esc_html(), 63, 149 enabling, local development document root, 28, 45–47 esc_sql(), 149 environment, 48–50 documentation, 402–403, 405 esc_textrea(), 149, 177 SAVEQUERIES, 27–28, 110 don’t hack the core!, 71–72, 382 esc_url(), 63, 149, 163 WP_DEBUG, 26, 28, 49 Don’t Repeat Yourself. See DRY E_STRICT, 49 default post types, 115–116 principle exclude_from_search, 118 default search, 331–332 downloading WordPress, 21–23 execution path analyzer, 344 default taxonomies, 126 DRY principle (Don’t Repeat external content, collecting, default_content Filter hook, Yourself), 220–224 294–303 154 duplicate content, 321–323 external resources, 406–407 defi ned period of time, 301–302 delegation, CMS, 367–368 delete_blog_option(), 276 E F Deleted, site status, 263 _e(), 143 F5 BIG-IP, 349 delete_option() , 157, 183 E_ALL, 49 Facebook, 292, 299 delete_post_meta(), 135–136 easy to fi nd content, 314 fake fully qualifi ed domain delete_site_option(), 276 e-commerce, CMS, 380 names, 50–51, 54 delete_transient(), 63 Edit Flow plugin, 370, 385 Fancy page template, 243 delete_user_meta(), 64 edit_item, 121, 131 FAQ section, readme.txt, 207 deleting metadata, 135–136 Editor role, 361–362 featured content pages, 373–376 deployment cycle, 42 edit_post_link(), 80 feeding WordPress upstream, 292 deprecated functions, 65–66 E-mail, mailing list, 406 feeds, CMS and, 393–395 deprecated.php fi le, 66 email_exists, 64 FeedWordPress plugin, 394 readme Description section, EMPTY_TRASH_DAYS, 31 File Monitor, WordPress, .txt, 207 enabling Multisite, 261–262 358–359414 bindex.indd 414 12/6/12 1:09 AM fi le permissions – hacking core fi le permissions, 30 fi nding, in core, 60–62 get_post_types(), 124get_ __FILE__ PHP constant, 146 formatting, 63 row(), 108 fi le structure, WordPress, 23 inline documentation, 59, 60 get_site_option(), 63, 276, file_get_contents(), 300 Multisite, 266–270 279 fi lename, plugin, 140 Options API, 63 get_sitestats(), 287 Filter hooks, 151–154 pluggable, 63 get_super_admins(), Filter Reference, 156 Plugin API, 64 61, 285 Firebug, 315, 386 in post process, 64 get_taxonomies, 65 First Post, 19–20 sanitizing, 150, 271 get_template_part(), 219, fi ve-minute installation, 2, 10, *_site_option(), 276–277 221, 223, 241 13, 19 special post type functions, get_the_term_list(), 133 fl ow, of Loop, 77–79 124–125 get_the_title(), 99 fl owchart, template hierarchy, taxonomy.php fi le, 65 getting noticed, 290–291, 233–234 User API, 64 320–329 folder structure, plugin, 140 widget functions, Halloween get_transient(), footer.php, 222 Store plugin, 192–194 63, 302 FORCE_SSL_ADMIN, 31, 356 working outside Loop, get_userdata, 63, 68 FORCE_SSL_LOGIN, 30–31, 62, 97–99 get_user_meta(), 64 356 Function Reference, 67–69, 133 get_users(), 64 force_ssl_login, 62 functions.php fi le global navigation, 246, 310, forcing SSL, on login, 356 described, 62 311, 312, 314, 318, form(), 192–193 theme creation, 238–240 376, 377 form nonce, 147 Twenty Eleven, 323 global variables, 93–97 formatting functions, 63 Gnu Public License. See GPL formatting.php fi le, 63 good passwords, 354 forms management, CMS and, G Google AdSense, 78, 304, 305, 306, 379–380 Gallery, post format, 250 307, 340 forums, CMS, 379 Gardner, Brian, 257 Custom Search Engine, 333, forward compatibility, generic XML data, 299–301 334 permalinks, 32 Genesis theme, 257 Maps, 298–299 404.php, 235–236 GeoMark, 328 trackbacks, 323–324 Freytag, Brian, 293 $_GET, 154 Webmaster Tools, 321, 322, front-page.php, 225–227 get_avatar, 63 327, 334 FS_CHMOD_DIR, 30 get_blog_count(), 286 XML Sitemaps plugin, FS_CHMOD_FILE, 30 get_blog_details(), 266 321–322 FTP installation, themes, get_blog_option(), 276 Google Analytics, 340–342 212–213 get_current_theme, 65 GPL (Gnu Public License), 5–6, fully qualifi ed domain names, get_currentuserinfo, 63 141–142, 185 50–51, 54 get_option(), 63, 157, 158, 162 Gravatar, 2 functions. See also core; specifi c get_permalink(), 97 Gravity Forms, 379–380 functions get_post(), 98–99 Griffi n, Clifton, H., 391 activating, 142–143 get_post_custom(), 64, 137 API, 62 get_post_format(), 219, 220 Codex, 67–69 get_post_meta(), 64, 99, 136, H deactivating, 142–143 137, 173 deprecated, 65–66 get_posts(), 64, 74, 75, 78, 81, Hackers, mailing list, 406 escaping, 111, 148–149, 177 82, 87–88, 374 hacking core, 71–72, 382415 bindex.indd 415 12/6/12 1:09 AM Halloween Store plugin – K.I.S.S. methodologyHalloween Store plugin, hosting options, WordPress, 8–9 insert(), 109 184–203 hosts fi le, 51, 52 installation problems, 14–17. complete source code hs_widget(), 192 See also WordPress (halloween-store.zip), .htaccess, 31–35. See also Installation section, readme 195–203 permalinks .txt, 207 meta box, 188–190 HTML interactivity features, CMS, settings page, 186–187 esc_html(), 149 379–380 shortcode, 190–191 esc_textrea(), 149, 177 internationalization (i18n), __() translation function, $_GET, 154 143–145, 184, 243 186 microformats, 327–329 intval(), 149 widget functions, 192–194 POSH, 324, 325, 327 IP addresses halloween_options, 185 $_POST, 154 blacklist, 351 halloween_sanitize_options, Semantic, 324–326 .htaccess, 35 188 separating concerns, 324 wildcard, 35 halloween-store.php, 184 valid, 326–327 IRC chat rooms, 405 halloween_store_settings_ wp_kses(), 150, 177 Irish, Paul, 329 page(), 186 XFN, 327, 328 $is_apache, 96 halloween-store.zip (plugin HTML5, 326, 329–330 is_array(), 61 source code), 195–203 HTML5Shiv, 329, 330 is_email(), 63 handle 404 errors, 235–236 HTTP API, 70 $is_IIS, 96 hardware scaling, enterprise-scale httpd.conf, 47, 48, 52 $is_iphone, 96 WordPress, 389–390 httpd-vhosts.conf, 51 $is_mobile, 96 has_archive, 118, 120, 123 HTTPS, 30, 31, 62, 146, 356 is_multisite(), 61, 62, 266, hashing salt values, 25, 113, 355 Hybrid Core theme, 257 268, 271, 277 has-patch, 399 HyperDB, 350, 390 ISO-639 language code, 29 hCard, 328 ISO-3166 country code, 29 header, plugin, 140–141, 184–185 is_single(), 82, 87, 153 header.php, 221–222 I is_super_admin(), 60, 62, 286 Hello Dolly, 58 i18n. See internationalization is_user_member_of_blog(), hiding WordPress version ID-driven URLs, 32 282, 283, 284 information, 353 Ideas area, WordPress, hierarchical argument, 118, 407–408 J 130 identity management, enterprise- high availability, load balancing, scale WordPress, 391–393 Jaquith, Mark, 50, 247, 376 350 images JavaScript, 316, 329. See also history, privacy and, 307–308 alt attributes, 326 statistics counters homepages post format, 250 JetPack, 342–343 CMS, 372–373 themes and, 214–215 Johnson, Charles, 394 front-page.php, 225–227 image.php, 233 JOIN, 75, 76, 105, 106, 114 home.php , 225, 234 in_array(), 61 jQuery Cycle plugin, 375 home_url(), 146 includes_url(), 146 hook into WordPress core, index.php fi le, 36, 218–220 401–402 init Action hook, 117, 128, 154, K hooks. See also specifi c Action 155, 185, 277, 283 KCacheGrind, 344 hooks; specifi c Filter hooks inline documentation, 59, 60 Action hooks, 151–156 keywords, Trac, 399 InnoDB, 388 King, Alex, 55, 257, 297 Filter hooks, 151–154 INSERT, 108, 109 Hooks Database, 407 K.I.S.S. methodology, 318416 bindex.indd 416 12/6/12 1:09 AM labels – multi-pass LoopsL sandbox, 41, 42, 43, 55 mailing lists, WordPress, 5, theme development, 53 405–406 labels virtual local server names, .maintenance fi le, 35–36 custom post types, 121–122 50–53 maintenance mode, 35–36 custom taxonomies, 131–132 web server document root, make.wordpress.org, 408 labels argument, 118, 121 46–48 MAMP, 10, 44, 45, 46, 47 LAMP (Linux, Apache, MySQL, WordPress install, 45–46 manual advertising placement, and PHP), 44–45, 346–347 local paths, plugins, 145–146 305–306 LANGDIR, 29 localization, 26, 29, 143, 145, 243 Marcotte, Ethan, 335 languages lock down wp-admin, 35 Mature, site status, 263 character set, 25 login Maunder, Mark, 359 internationalization, forcing SSL on login, 356 McInvale, Matt, 378 143–145, 184, 243 limiting login attempts, 354 media directory, wp-content/ localization, 26, 29, 143, Loops, 73–100 uploads, 37–38 145, 243 advanced queries, 91–92 Media Library, WordPress, 33, 37 multilanguage capabilities, content display, 73 Meetups, WordPress, 4, 407 WordPress, 26 customizing, 75, 81–82 memcache, 345, 388 Unicode UTF-8, 25 diagram, 76 memcached, 345 WordPress localizer, 29 fl ow, 77–79 menu, plugin settings page, WPLANG option, 26, 29 get_posts(), 81, 82, 87–88 158–160 latest.tar.gz, 22 global variables, 93–97 menu management latest.zip, 22 Halloween Store plugin, 194 disconnect, 247, 248, 377 LDAP, 391–392 multi-pass, 91 theme enhancement, leave it alone paradigm, mobile navigation links in, 85–86 246–248 access, 334–335 nested, 90–91 menu_icon, 119 Lessig, Lawrence, 5 overview, 73–74 menu_name, 131 lighttpd, 9, 387 page content generation, menu_position, 119 lightweight mobile, 335 74–75 meta boxes, 169–174, 188–190 limit login attempts, 354 paging in, 85–86 meta_compare parameter, 91–92 Link, post format, 250 parameters, 83–85 metadata, 133–137 link categories, 126 query parameters to SQL, microformats, 327–329 Linux, 213. See also LAMP 75–76 mirmillo.com, 51, 54 Little, Mike, 2 query_posts(), 81, 86–87 mirmillo.local, 51, 52, 53, 54 load balancing, 349–350 resetting Loop data, 88–90 MO (machine object) language load_plugin_textdomain(), template tags, 79–81, 96–97 fi les, 26 145 themes, 76–77 mobile access, user experience, local development environment, understanding, 74–79 334–335 41–55 working outside of, 97–99 moderation method, comments, benefi ts, 43–44 WP_Query object, 82 351 best practice, 41 loop, showcase, 226–227 Modernizr, 329, 330 confi guration details, 46–53 lorem ipsum, 318 monetizing WordPress site, defi ned, 42 303–304 deploying local changes, more tag, 81 53–55 M MU (multi-user). See Multisite deployment cycle, 42 Machado, Eddie, 256 Mugford, Dale, 335 enabling debugging, 48–50 machine object. See MO Mullenweg, Matt, 2, 3. See also plugin development, 53 magazine themes, 256, 257 Automattic reasons for using, 42–43 multi-pass Loops, 91417 bindex.indd 417 12/6/12 1:09 AM Multisite (WordPress Multisite) – option.php fi leMultisite (WordPress Multisite), Multisite sites navigation 259–288 add users, 284 consistent, 310–312 advantages, 261 creating, 263–264, 270–274 global, 246, 310, 311, 312, Blog ID (site ID), 260, defi ned, 260 314, 318, 376, 377 265–266 managing, 263–264 links, in Loop, 85–86 blogs.dir directory, 37, restore_current_blog(), needs-codex, 399 38, 261 267, 268, 269, 270 needs-docs, 399 coding for, 265–287 restoring, 267–270 needs-patch, 399 content integration via feeds, site-specifi c database tables, needs-refresh, 399 393–394 287–288 needs-testing, 399 database schema, 287–288 site-specifi c options, 276 needs-ui, 399 enabling, 261–262 statuses, 263 needs-unit-tests, 399 functions, 266–270 switching, 267–270 nested Loops, 90–91 is_multisite(), 61, 62, Multisite-specifi c database tables, network. See Multisite network 266, 268, 271, 277 287 Network Admin. See Multisite local setup, 53 multi-user (MU). See Multisite Network Admin options, 276–282 /mu-plugins directory, 37, 146, network_admin_menu Action plugins, 264–265 283 hook, 274–275 restore_current_blog(), MyISAM, 388, 390 new.example.com, 27, 112 267, 268, 269, 270 MySQL. See also database; SQL new_item, 121 shortcode example (prowp2- bbPress, 2, 379, 380, 403, new_item_name, 131 multisite-shortcode. 404, 405 news sites, WordPress, 409–410 zip), 268–270 caching hierarchy, 343 NextGen Gallery plugin, 37, 38 Super Admins, 61, 260, 265, credentials, 357 next_posts_link(), 97, 98 285–286 enterprise-scale WordPress, NFS/Samba share, 349 switch_to_blog(), 267, 388 nginx, 44, 387 268, 269, 270 errors, wpdb class, 110–111 Nielson, Jakob, 318 terminology, 260 esc_sql(), 149 nonces themes, 264 hosting prerequisites, 9 check_admin_referer(), understanding, 259–262 LAMP, 44–45, 346–347 147–148, 190, 280 WordPress MU, 2, 8, 259 load balancing, 349 defi ned, 147 WordPress versus, MAMP, 10, 44, 45, 46, 47 secret keys, 147–148 260, 261 MySQL-WordPress Settings API, 160 Multisite network confi guration, 14–17 wp_nonce_field(), 62, defi ned, 260 query cache, 348 147, 148, 171 network-wide options, terminology, 9 not_found, 121 276–282 WAMP, 45, 46, 47, 48, 49, not_found_in_trash, 121 roles, 264 51, 213 settings (prowp2- WAMPSERVER, 45, 47 multisite-network- mysql_error(), 15, 16 O settings.zip), 280–282 OAuth, 393 Settings menu, 265 N object caching, WordPress, 347 stats, 286–287 oEmbed, 294–295, 296, 297, users, 264, 282–285 _n(), 144 298, 381 working in, 262–265 naked themes, 215 opcode cache, 345 Multisite Network Admin, 263 name, custom label, 121, 131 OpenID, 392–393 Multisite Network Admin menus, nameplate, 221 OpenID plugin, 392–393 274–275 Nav Menus, default post type, 116 option.php fi le, 63418 bindex.indd 418 12/6/12 1:09 AM options, Multisite – Plugin Directory options, Multisite, 276–282 the_permalink() template deactivating functions, Options API, 63, 70, 182, 302 tag, 80 142–143 Options API functions, 63 permissions determining paths, 145–146 options page, plugin, 160–169 Apache, 356–357 fi lename, 140 ordering parameters, 84 PHP folder structure, 140 O’Reilly, Tim, 7 Alternative PHP Cache, 345 hacking core compared to, outline structures, 319 bbPress, 2, 379, 380, 403, 72 Ozz, Andrew, 372 404, 405 header, 140–141, 184–185 confi guration, .htaccess, internationalization, 34 143–145 P error level, 49 license, 141–142 LAMP, 44–45, 346–347 P2 theme, 371, 408 local development MAMP, 10, 44, 45, 46, 47 pages environment, 53 opcode cache, 345 as content, 76 local paths, 145–146 WAMP, 45, 46, 47, 48, 49, content generation, Loop, meta box creation, 169–174 51, 213 74–75 Multisite, 260, 264–265 WAMPSERVER, 45, 47 parameters, 83 /mu-plugins directory, 37, web server caching, 345–346 Page, default post type, 115 146, 283 WordPress, 2 Page Links To plugin, 376 options, 156–158, 157–158 PHPDoc, 59 Page re-Mash, 377–378 options page, 160–169 php_error.log, 28 Page Speed, 315 overview, 139–140 php-errors.log, 35 page templates (custom page packaging, 140–146 php.ini fi le, 28, 49, 345–346, templates), 243–245 publishing, to Plugin 387, 391 page.php, 232–233 Directory, 204–209 phpMyAdmin tool, 10, 14, 44, paging, in Loop, 85–86 search your site, 332–334 46, 54, 111, 388 parameters. See also Loops security, 147–151, 357–360 php_value memory_limit, 28, meta_compare, 91–92 settings, 156–169 34 types, 83–85 shortcodes, 174 PHPXref for WordPress, 407 parent themes, 215, 216, 217, themes compared to, 215 Ping-o-Matic, 323, 324 218, 220, 252, 253, 254, 255, uninstalling, 182–183 pings, 323–324 256. See also child themes URL paths, 146 Planet WordPress, 410 parent_item, 131 widget creation, 175–179 pluggable functions, 63 parent_item_colon, 121, 131 WordPress integration, pluggable.php fi le, 63 parse_query(), 74, 82 169–183 plugins, 139–210. See also passwords, 354 wp-content directory, 38 Halloween Store plugin; patch/Diff fi le, 402 wp-content/plugins specifi c plugins paths determination, plugins, directory, 36–37 activating functions, 145–146 WP_PLUGIN_DIR, 27 142–143 performance tuning, enterprise- WP_PLUGIN_URL, 27 advertising, 304–305 scale WordPress, 386–388 Plugin API, 64, 69 array of options, 157–158, Perl, 45, 338 Plugin API functions, 64 185 permalinks Plugin Description fi eld, 204 custom database tables, advantages, 32–33 Plugin Directory 180–182 enabling, 32 online reference, 156, 407 Dashboard Widgets, get_permalink(), 97 publishing plugin to, 179–180 SEO, 320–321 204–209 data validation, 148–151 the_permalink Filter hook, release new plugin version, deactivate, 37 153 210419 bindex.indd 419 12/6/12 1:09 AM Plugin Name section – reference, core as Plugin Name section, 204, 206 post_type_exists(), 125 prowp_register_widgets(), plugin settings page Pound, 349 175, 178 Halloween Store plugin, premium themes, 256–258. See prowp_sanitize_options(), 186–187 also theme frameworks 162 menu, 158–160 prepare(), 106–107, 109 prowp_sanitize_settings(), submenus, 158–160 previous_posts_link, 97, 98 166 top-level menu, 158–159 printf(), 14, 144 prowp_save_meta_box(), 171 plugin submission, 402 privacy prowp_setting_section(), Plugin URL fi eld, 204 history and, 307–308 166, 167 plugin_dir_path(), 64, local development prowp_settings_init(), 166 145–146 environment, 42–43 prowp_settings_page(), 160, plugin_dir_url(), 64 progressive enhancement, 161 plugin.php fi le, 64 330–331 prowp_widget(), 176 Plugins SubPanel, 36, 142, 143 project themes, 215–216. See also Public, site status, 263 plugins_url(), 146 child themes public argument, 117, 130 PO (portable object) fi les, 26 Project Wonderful, 304, 306 publicly_queryable, 117 podcasts, WordPress, 408–409 prowp, 142 publishing plugins. See Plugin Pods Framework plugin, 379 prowp2-custom-meta-box.zip, Directory pony-and-rainbow example, 224, 172–174 publish_post, 154 229 prowp2-custom-widget.zip, popular_items, 131 178–179 portability, themes, 215, 238, 242 prowp2-multisite-add- Q users.zip, 284 portable object. See PO queries. See also MySQL; SQL prowp2-multisite-network- POSH, 324, 325, 327 advanced, Loops, 91–92 settings.zip, 280–282 $_POST, 154 MySQL query cache, 348 prowp2-multisite- _post(), 77, 78, 82, 93 SAVEQUERIES, 27–28, 110 shortcode.zip, 268–270 posts simple database queries, prowp2-reading-settings- as content, 76 106–108 plugin.zip, 168–169 parameters, 83 query array, in themes, 28 prowp2-settings-api- Post, default post type, 115 query parameters to SQL, 75–76 plugin.zip, 163–164 post formats query_posts(), 81, 86–87 prowp_create_menu(), 159 get_post_format(), 219, query_var, 119, 129, 130 prowp_custom_css(), 155 220 QuickPress panel, 19, 318 prowp_email_new_comment(), list, 250 Quote, post format, 250 themes, 249–250 152 Twitter Tools, 298 prowp_function(), 151 $post global variable, 93–94 prowp_install(), 142 R post process, functions in, 64 prowp_meta_box(), 170 post revisions, WP_POST_ prowp_meta_box_init(), 170, rainbow-and-pony example, 224, REVISIONS, 27 172 229 post statuses, 104 prowp_multisite_create_ RAMP, 55, 257, 386 post types sites(), 271, 273 Readme Standard, 206 custom, 116–125 prowp_plugin_options, readme.txt fi le, plugin custom post type template 157 submission, 204–208 fi les, 123–124 prowp_profanity_filter(), readme.txt validator, 206 default, 115–116 152 Reddit, 347 labels, 121–122 prowp_register_settings(), redirects, URL, 34 post_status fi eld, 104 161 reference, core as, 58–66420 bindex.indd 420 12/6/12 1:09 AM register custom post types – set_post_thumbnail() register custom post types, roles, 360–364 search engine optimization (SEO) 116–121 capabilities overview, getting found, 320–324 register_activation_hook(), 362–363 permalinks, 32, 320–321 64, 142, 143, 185 CMS, 367–368 starter theme, 216 register_deactivation_hook, extending, 363–364 search engine results page (SERP), 64, 143, 183 Multisite network, 264 240–241, 320 register_nav_menu(), 246 root directory Search Everything, 333 register_post_type(), 64, .maintenance fi le, 36 search tickets, Trac software, 400 116, 121 modifying fi les, 23 searchform.php, 242 register_setting(), 161, 168, php-errors.log, 35 searching your site, 331–334 188 WordPress installation, 10 search_items, 121, 131 register_taxonomy(), 65, 128, wp-config.php, 24 search.php, 240–242 129, 130, 133 Roots theme, 257–258 2nd-opinion, 399 register_uninstall_hook, round-robin DNS, 349 secret keys 183 RSS feeds, CMS and, 393–395 nonces, 147–148 relationships, taxonomy, 127 rsync, 349 using, 355–356 Release Archive, 22–23 rtl-feedback, 399 wp-config.php, 25 releasing new plugin version, security, 352–360. See also Plugin Directory, 210 attacks; SSL Relevanssi, 333 S Apache permissions, remove users, 284 salt values, 25, 113, 355 356–357 reporter-feedback, 399 sandbox, 41, 42, 43, 55 good passwords, 354 reports, Trac, 400 sanitization .htaccess, 35 “Requires at least” fi eld, readme data validation, 148–151 login attempts, 354 .txt, 206 halloween_sanitize_ move confi guration fi le, 354 resetting Loop data, 88–90 options, 188 move content directory, 355 resources, 404–410. See also prowp_sanitize_ MySQL credentials, 357 Codex options(), 162 plugins, 147–151, 357–360 responsive web design, 335–336 prowp_sanitize_ secret keys REST API, 300, 301 settings(), 166 nonces, 147–148 REST web service commands, sanitizing functions, 150, using, 355–356 244 271 wp-config.php, 25 restore_current_blog(), 267, sanitize_email(), 150, 163 table prefi x changes, 25–26, 268, 269, 270 sanitize_text_field(), 63, 354 restoring sites, 267–270 150, 163, 172, 177, 193, 280 Theme Installer, 213 retrieving metadata, 136–137 save_post Action hook, 171, WordPress updates, 352–353 reusable parts, 220–224 172 WordPress version Revision, default post type, 116 SAVEQUERIES, 27–28, 110 information, 353 Revolution theme, 257 scalability. See also cache wp-config.php, 24, 25–26 rewind_posts(), 91 management Seidel, Oliver, 379 Rewrite API, 70 cache management, 343–348 Semantic HTML, 324–326 rewrite argument, 120, 130 enterprise-scale WordPress, SEO. See search engine rewriting rules, .htaccess, 386–390 optimization 33–34 load balancing, 349–350 separate_items_with_commas, Rich Text Widgets plugin, 371 SCP, 212 131 robots.txt fi le, 322–323 Screenshots section, readme. separating concerns, 324 Role Scoper plugin, 363, 367 txt, 207 SERP. See search engine results page set_post_thumbnail(), 64421 bindex.indd 421 12/6/12 1:09 AM set_post_type() – tags set_post_type(), 125 Slashdot, 347 subdomain example, Multisite, Settings API, 70, 160–163, 164, slideshows, 226–227, 232, 245 260 167, 187, 251 social media buttons, 291–293 submenus, plugin settings page, Settings menu, Multisite network, Social Media Widget plugin, 293 158–160 265 social networking badges, submitting plugin, 204. See also set_transient(), 63, 302 292–294 Plugin Directory setup_postdata(), 78, 88, 95, software development workfl ow, Subscriber role, 361 99 42 Subversion. See SVN SFTP, 53, 212 spam, 350–352 Super Admin role, 362 ShareThis plugin, 291 Spam, site status, 263 Super Admins, 61, 260, 265, sharing, permalinks, 33 special post type functions, 285–286 Shiftlett, Chris, 321 124–125 Super Cache plugin, 38, 347, 388, shortcodes sprintf(), 144 390 example (prowp2- SQL. See also MySQL Support Forum Volunteers, multisite-shortcode. injection attacks, 26, 106, mailing list, 406 zip), 268–270 111, 148 support forums, 404 Halloween Store plugin, INSERT, 108, 109 supports argument, 118 190–191 JOIN, 75, 76, 105, 106, 114 survey, WordPress, 3–4 plugins, 174 query format, 75 SVN (Subversion) Shortcode API, 69–70, 174 UPDATE, 108, 109 clients, 208 showcase loop, 226–227 WHERE clause, 75, 108, 109 described, 22 showcase.php, 245 SSL hook into WordPress core, show_in_admin_bar, 119 FORCE_SSL_ADMIN, 31, 356 401–402 show_in_menu, 119 FORCE_SSL_LOGIN, 30–31, setup, publishing plugins, show_in_nav_menus, 118, 130 62, 356 208–209 show_tagcloud, 130 force_ssl_login, 62 TortoiseSVN, 208–209, 210, show_ui, 117, 130 forcing, on login, 356 401–402 sidebar-page.php, 245 HTTPS, 30, 31, 62, 146, 356 Trac software, 401 sidebar.php, 222–223 plugins_url(), 146 understanding, 401 Simple LDAP Login plugin, 391 Stable tag, readme.txt, 206 updates, mailing list, 406 single.php, 231–232 staging, deployment cycle, 42 SVN Commit, 209, 210 singular_name, custom label, StartBox theme, 258 switching sites, 267–270 121, 131 starter themes, 216–217, 256 switch_theme, 154 sister projects. See also WordPress State of the Word keynote, 3 switch_to_blog(), 267, 268, Developer Community statistics counters, 337–343 269, 270 bbPress, 2, 379, 380, 403, AWStats, 338–340 syntax highlighting, 59 404, 405 Google Analytics, 340–342 BuddyPress, 2, 380, 382, JetPack, 342–343 403, 405 Status, post format, 250 T future projects, 403 statuses, site, 263 tables. See database tables sites. See Multisite sites stay updated, 352–353 table prefi x, changing, 25–26, site ID. See Blog ID Storey, Duane, 335 354 site load times, 314–315 structuring information, user $table_prefix, 25, 287 SITECOOKIEPATH, 29 experience, 318–319 Tadlock, Justin, 257 *_site_option() functions, style.css fi le, 217–218 tags 276–277 subdirectory example, Multisite, content sharing sites and, site_url(), 146 260 324422 bindex.indd 422 12/6/12 1:09 AM tag cloud – the_title Filter hookHTML5, 326, 329–330 text editors, 59 Twenty Twelve, 58, 212 parameters, 81, 84 the_author, 80 widget areas, 248–249 taxonomy, 126 the_author_meta(), 95, 99 #wordpress-themes, 405 tag cloud, 97, 130, 132, 235, 241, the_category(), 80 wp-content/themes 404 the_content Filter hook, 151, directory, 37 tag.php, 230 152, 153 theme creation, 215–243. See also tags folder, SVN, 209 the_content_rss, 153 content display tar archives, 22 the_content()template tag, additional fi les, 235–243 taxonomies 80, 81 author.php, 236–237 custom, 128–133 the_excerpt(), 80, 241 comments.php, 237–238 default, 126 the_ID(), 80 404.php, 235–236 get_taxonomies, 65 Thematic theme, 240, 258, 371 functions.php, register_taxonomy(), 65, themes, 211–258. See also child 238–240 128, 129, 130, 133 themes; theme creation; theme searchform.php, 242 relationships, 127 frameworks; Twenty Eleven; search.php, 240–242 table structure, 126–127 specifi c themes getting started, 217–220 wp_insert_term, 65 assets, 214–215 index.php fi le, 218–220 wp_update_term, 65 barebones, 215 project themes vs. child taxonomies argument, 119 Bones, 256 themes, 215–216 Taxonomy API, 65 CMS support, 370–372 reusable parts, 220–224 taxonomy tables, 105–106 commercial, 3, 256, 257, 258 starter themes, 216–217 taxonomy.php fi le, 65 core, 58 style.css fi le, 217–218 Technorati.com, 324, 327 described, 213–215 Theme Customizer, 251 template fi les. See also specifi c enhancements, 246–251 Theme directory, 212, 402, 407 template fi les functions, 212 theme frameworks, 256–258 archival templates, 231 images, 214–215 Carrington theme, 257 custom post type, 123–124 installing, 212–213 Genesis theme, 257 defi ned, 214 local development purpose, 215–216, 256 template hierarchy environment, 53 sidebar.php, 223 archival, 231 Loop, 76–77 StartBox theme, 258 attachment.php, 233 magazine, 256, 257 Thematic theme, 240, 258, category.php, 229 menu management, 246–248 371 content display, theme Multisite, 260, 264 theme creation, 215 creation, 233–234 naked, 215 theme hierarchy defi ned, 233 overview, 211 child themes, 251–256 fl owchart, 233–234 P2, 371, 408 style.css fi le, 218 front-page.php, 225 plugins compared to, 215 Theme Installer, 213 index.php, 220 portability, 215, 238, 242 Theme Repository, 3, 53 template tags post formats, 249–250 Theme Settings Control Panel, described, 79–81 premium, 256–258 250–251 global variables versus, professional, 258 theme submission, 402 96–97 project, 215–216 the_permalink Filter hook, 153 parameters, 81 query array, 28 the_permalink() template tag, “Tested up to” fi eld, readme reasons for using, 211–212 80 .txt, 206 starter, 216–217, 256 the_tags(), 80 Testers, mailing list, 406 Theme Repository, 3, 53 the_time, 80 testing, deployment cycle, 42 Twenty Ten, 58, 212 the_title Filter hook, 153, 154423 bindex.indd 423 12/6/12 1:09 AM the_title() template tag – user experience the_title() template tag, 80, HTML5 tag elements, 217, update_count_callback, 130 81 329–330 update_item, 131 three clicks rule, 318 index.php, 219 update_option(), 63, 156–157 $300 million difference, 316 Loop in, 79 update_post_meta(), 135, 172 tickets, Trac software, 398–401 MySQL query cache, 348 updates, security and, 352 time(), 36 page templates, 245 update_site_option(), 63, _time(), 80 post formats, 250 276, 280 time parameters, 84 searchform.php, 242 updating metadata, 135 timeline, Trac, 401 search.php, 240, 241 /upgrade directory, 38 TinyMCE, 371 sidebar.php, 223 Upgrade Notice section, readme TinyMCE Advanced plugin, 372 single.php, 231 .txt, 208 top-level menu, plugin settings style.css, 218 upgrades, WordPress, 352 page, 158–159 the_excerpt(), 241 /uploads directory, 37–38, 349 Torbert, Michael, 357 theme creation, getting uploads directory, load balancing, TortoiseSVN, 208–209, 210, started, 217–220 349 401–402 Theme Customizer, 251 URLs Trac keywords, 399 trackbacks, 323 beautiful, 321 Trac mailing list, 406 Twitter Tools, 298 canonical, 76 Trac software, 398–401 widget areas, 248, 249 esc_url(), 149, 163 trackbacks, 323–324 Twenty Ten, 58, 212 ID-driven, 32 traffi c statistics. See statistics Twenty Twelve, 58, 212 nonce, 148 counters twenty_eleven(), 323 paths, plugins, 146 transient caches, 301–303, twentyeleven_setup(), 239 redirects, 34 347–348, 388 Twitter usability, 316–318 translation functions, 143, 145, API, 70, 297 usability testing, 316–318 184, 186 Bootstrap, 257 users, Multisite network, 264, __() translation function, 143, 404 error, 235 282–285 186 integrating, 296–298 User API functions, 64 trash bin, 31, 104 shortcodes, 174 user experience, 309–336 trunk folder, SVN, 209 Status post format, 250 consistent navigation, Tweetily, 292 Tools plugin, 297–298 310–312 Twenty Eleven WordPress conversation, 7 CSS3, 330–331 archive.php, 228 easy to fi nd content, 314 attachment.php, 233 getting found, 320–324 author.php, 237 U HTML5, 329–330 JavaScript usage, 316 Automattic, 212 Ubuntu Linux, 213 mobile access, 334–335 category.php, 228 UI Group, 399, 405 principles, 309–316 child theme, 253–254 ui-feedback, 399 questions to ask, 310 comments.php, 238 Unicode UTF-8, 25 responsive web design, copy, 218 Uninstall hook, 182, 183 335–336 core theme, 58 uninstalling plugins, 182–183 searching your site, 331–334 CSS, 311 uninstall.php, 140, 182, 183, site load times, 314–315 footer.php, 222 184, 194–195 structuring information, 404.php, 235 unique ID fi eld, 102, 103 318–319 front-page.php, 227 UPDATE, 108, 109 functions.php usability, 316–318 , 323 update(), 109, 177, 193–194 usability testing, 316–318 get_post_format(), 220 update_blog_option(), 276424 bindex.indd 424 12/6/12 1:09 AM username_exists() – #wordpress-ui visual design elements, widget areas, theme Meetups, 4, 407 312–313 enhancement, 248–249 multilanguage capabilities, web standards, 324–329 widget functions, Halloween 26 username_exists(), 64 Store plugin, 192–194 Multisite versus, 260, 261 user.php fi le, 64 widgets_init Action hook, 175, news sites, 409–410 user_register Action hook, 178 Notable Users showcase, 4 155, 156 wildcard IP addresses, 35 PHP, 2 ux-feedback, 399 Word, Ben, 257 Planet, 410 WordCamps, 3, 4, 407 podcasts, 408–409 WordFence Security plugin, popularity, 3–6 V 359–360 Release Archive, 22–23 Valdrighi, Michel, 2 WordPress. See also content survey, 3–4 valid HTML, 326–327 management system; system complexity, 344–345 version information, WordPress, enterprise-scale WordPress; #wordpress, 405 353 resources; WordPress WordPress core. See core version_compare(), 142 Developer Community WordPress database. See database Video, post format, 250 Alltop, 410 WordPress Developer view tickets, Trac software, 400 bleeding-edge version, 22, Community, 397–410. view_item, 121 401 See also sister projects VIP Program, WordPress, 385 chat, 405 contributing to WordPress, virtual local server names, 50–53 in commercial situations, 397–403 visual design elements, 312–313 5–6 development updates, 408 community intersection, 4–5 documentation, 402–403 cron, 31, 338 hacking core, 72 W current state, 3–4 overview, 2 defi ned, 1–2 plugin submission, 402 W3 Total Cache, 347 development updates, 408 resources, 404–410 Walters, Matt, 358 directories, 23 theme submission, 402 WAMP, 45, 46, 47, 48, 49, 51, downloading, 21–23 Trac software, 398–401 213 external resources, 406–407 working on core, 401–402 WAMPSERVER, 45, 47 feeding WordPress upstream, WordPress File Monitor, 358–359 web server caching, 343, 345–347 292 WordPress in enterprise. See web standards, 324–329 fi le structure, 23 enterprise-scale WordPress WebGrind, 344 GPL, 5–6 WordPress in Your Language Webmaster Tools, Google, 321, history, 2 Codex page, 26 322, 327, 334 hosting options, 8–9 WordPress Language File WHERE clause, 75, 108, 109 Ideas area, 407–408 Repository, 26 widget(), 194 installation WordPress MU. See Multisite widgets do it yourself, 10–17 WordPress Multisite. See CMS support, 370–372 fi ve-minute, 2, 10, 13, 19 Multisite creating, 175–179 local development WordPress VIP Program, 385 Dashboard Widgets, environment, 45–46 wordpress.com, 4 179–180 problems, 14–17 #wordpress-dev, 405 Dashboard Widgets API, integration, plugins, 169–183 wordpress.org, 4 70, 179 localizer, 29 #wordpress-themes, 405 prowp2-custom-widget mailing lists, 5, 405–406 WordPress.TV, 3, 407 .zip, 178–179 Media Library, 33, 37 #wordpress-ui, 405 Widgets API, 69, 175, 179425 bindex.indd 425 12/6/12 1:09 AM workfl ow, CMS and – XAMPP workfl ow, CMS and, 368–370 wp-content/upgrade directory, WP_PLUGIN_URL, 27 WP e-Commerce plugin, 380 38 wp_postmeta, 103, 134 WP Late Night, 409 wp-content/uploads directory, WP_POST_REVISIONS, 27 WP Security Scan plugin, 26, 37–38, 349 wp_posts, 103, 104, 105, 106, 354, 357–358 WP_CONTENT_URL, 27 108, 112, 114 wp_2_commentmeta, 288 wp_dashboard_setup Action WP_Query object, 82, 122–123 wp_2_comments, 288 hook, 180 wp_rand, 63 wp_2_links, 288 WP-DB Backup plugin, 38 WPRealm.com, 409 wp_2_options, 288 wpdb class. See database class wp_redirect, 63 wp_2_postmeta, 288 wp-DBManager plugin, 54, 388 wp_registration_log, 287 wp_2_posts, 288 WP_DEBUG, 26, 28, 49 wp_reset_postdata(), 88–89 wp_2_term_relationships, WPEngineer.com, 409 wp_reset_query(), 88, 89–90 288 WP-Exploit Scanner, 358 WP-Security Scan, 357–358 wp_2_terms, 288 wp_foot(), 222 wp_set_password, 63 wp_2_term_taxonomy, 288 wp_footer, 154, 155 wp_signups, 287 wp_add_dashboard_widget(), WPForce.com, 409 wp_site, 287 180 wp_get_current_user(), 61 wp_sitecategories, 287 wp-admin, 23, 35 wp_get_theme(), 66 wp_sitemeta, 287 wp_blogs, 287 wp_head, 154, 155, 156, 221 WP_SITEURL, 26 wp_blog_versions, 287 WP_HOME, 26 WP-Super Cache, 347 wp-cache-config.php, 38 wp-includes, 23, 62–65 wp_tag_cloud(), 97, 132 WPCandy.com, 53, 409 wp_insert_post, 64 wp_term_relationships, 103, WP-CMS Post Control, wp_insert_term, 65 105, 106, 126, 127 368–369 wp_insert_user, 64 wp_terms, 103, 105, 126 wp_commentmeta, 103 wp_kses(), 150, 177 wp_term_taxonomy, 103, 105, wp_comments, 103, 105, 113, WPLANG option, 26, 29 126, 127 114, 388 wp_links, 103 wp_title, 153 wp-config.php, 24–31 wp_list_bookmarks(), 97 WPTouch, 335 changing table prefi x, wp_list_categories(), 97, 98 wp_transition_post_ 25–26, 354 wp_list_comments(), 238 status(), 369 moving, to parent directory, wp_list_pages(), 97, 246, 247, WP_UNINSTALL_PLUGIN, 183, 24, 354 378 195 moving content directory, wp-login.php, 33, 58 wp_update_term, 65 27, 355 wp_logout, 63 wp_update_user, 64 WordPress installation, 11 wp_mail, 63 wp_upload_dir(), 146 wp-config-sample.php, 10, WP_MEMORY_LIMIT, 28 wp_usermeta, 103, 114, 287 24, 402 wpmu_create_blog(), 270–271, wp_users, 103, 104, 105, 113, wp-content directory, 36–38 272, 273 114, 287 wp-content/advanced-cache. wp_nav_menu(), 247, 270 $wp_version, 142 php, 30, 38 wp_nonce_field(), 62, 147, WP_Widget class, 175–176 WP_CONTENT_DIR, 27 148, 171 wp-content/plugins directory, wp_options, 103, 112, 113, 157, 36–37 280 X wp-content/themes directory, wp_page_menu(), 98 _x(), 145 37 WP_PLUGIN_DIR, 27 XAMPP, 10, 45426 bindex.indd 426 12/6/12 1:09 AM XHTML Friends Network (XFN) – Zombie categoryXHTML Friends Network Y Z (XFN), 327, 328 XML Yet Another Related Post plugin, zed1.com, 2 data, generic, 299–301 378 Zen Garden, CSS, 324 Google XML Sitemaps YouTube video integration, zip archives, 22 plugin, 321–322 295–296 Zombie category, 86, 87, XML-RPC, mailing list, 405 YSlow!, 315, 386 229, 230 XSS. See cross-site scripting427 bindex.indd 427 12/6/12 1:09 AM Try Safari Books Online FREE for 15 days and take 15% off for up to 6 Months* Gain unlimited subscription access to thousands of books and videos.With Safari Books Online, learn without limits from thousands of technology, digital media and professional development books and videos from hundreds of leading publishers. With a monthly or annual unlimited access subscription, you get: • Anytime, anywhere mobile access with Safari To Go apps for iPad, iPhone and Android • Hundreds of expert-led instructional videos on today’s hottest topics • Sample code to help accelerate a wide variety of software projects • Robust organizing features including favorites, highlights, tags, notes, mash-ups and more • Rough Cuts pre-published manuscriptsSTART YOUR FREE TRIAL TODAY! Visit: www.safaribooksonline.com/wrox*Discount applies to new Safari Library subscribers only and is valid for the fi rst 6 consecutive monthly billing cycles. Safari Library is not available in all countries. badvert.indd 428 12/6/12 1:08 AM Related Wrox BookProfessional WordPress Plugin Development ISBN: 978-0-470-91622-3 As one of the most popular open source content management systems available today, WordPress boasts a framework that allows you to easily customize and extend it through plugins. This comprehensive book shows you how plugins work, reviews the tools and APIs in WordPress, and demonstrates how to extend the functionality of WordPress with plugins. The trio of authors provides a practical, solutions-based approach along with a collection of timely examples and plenty of code, all aimed at clearly explaining how to create a plugin file, work with users, integrate widgets, add menus and submenus, secure your plugins, and more. You will quickly come to understand how to develop custom plugins so that you can take WordPress to the next corporate and enterprise level. Related Wrox BookProfessional WordPress Plugin Development ISBN: 978-0-470-91622-3 As one of the most popular open source content management systems available today, WordPress boasts a framework that allows you to easily customize and extend it through plugins. This comprehensive book shows you how plugins work, reviews the tools and APIs in WordPress, and demonstrates how to extend the functionality of WordPress with plugins. The trio of authors provides a practical, solutions-based approach along with a collection of timely examples and plenty of code, all aimed at clearly explaining how to create a plugin file, work with users, integrate widgets, add menus and submenus, secure your plugins, and more. You will quickly come to understand how to develop custom plugins so that you can take WordPress to the next corporate and enterprise level. </div> </article> </div> </div> </div> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.1/jquery.min.js" crossorigin="anonymous" referrerpolicy="no-referrer"></script> <script> var docId = 'ec931691c95c7757f462425e8e52aaeb'; var endPage = 1; var totalPage = 460; var pfLoading = false; window.addEventListener('scroll', function () { if (pfLoading) return; var $now = $('.article-imgview .pf').eq(endPage - 1); if (document.documentElement.scrollTop + $(window).height() > $now.offset().top) { pfLoading = true; endPage++; if (endPage > totalPage) return; var imgEle = new Image(); var imgsrc = "//data.docslib.org/img/ec931691c95c7757f462425e8e52aaeb-" + endPage + (endPage > 3 ? ".jpg" : ".webp"); imgEle.src = imgsrc; var $imgLoad = $('<div class="pf" id="pf' + endPage + '"><img src="/loading.gif"></div>'); $('.article-imgview').append($imgLoad); imgEle.addEventListener('load', function () { $imgLoad.find('img').attr('src', imgsrc); pfLoading = false }); if (endPage < 5) { adcall('pf' + endPage); } } }, { passive: true }); if (totalPage > 0) adcall('pf1'); </script> <script> var sc_project = 11552861; var sc_invisible = 1; var sc_security = "b956b151"; </script> <script src="https://www.statcounter.com/counter/counter.js" async></script> </html>